WIP

Author: cameroncooke

.smithery/index.cjs

@@ -223,14 +223,14 @@ export async function someToolLogic(
   executor: CommandExecutor,
 ): Promise<ToolResponse> {
   log('info', `Executing some_tool with param: ${params.requiredParam}`);
-  
+
   try {
     const result = await executor(['some', 'command'], 'Some Tool Operation');
-    
+
     if (!result.success) {
       return createErrorResponse('Operation failed', result.error);
     }
-    
+
     return createTextResponse(`✅ Success: ${result.output}`);
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : String(error);
@@ -243,7 +243,7 @@ export default {
   name: 'some_tool',
   description: 'Tool description for AI agents. Example: some_tool({ requiredParam: "value" })',
   schema: someToolSchema.shape, // Expose shape for MCP SDK
-  
+
   // 5. Create the handler using the type-safe factory
   handler: createTypedTool(
     someToolSchema,
@@ -260,6 +260,15 @@ This pattern ensures that:
 - Import paths use focused facades for clear dependency management
 ```
 
+### Debugger Subsystem
+
+The debugging workflow relies on a long-lived, interactive LLDB subprocess. A `DebuggerManager` owns the session lifecycle and routes tool calls to a backend implementation. The default backend is the LLDB CLI (`xcrun lldb --no-lldbinit`) and configures a unique prompt sentinel to safely read command results. A stub DAP backend exists for future expansion.
+
+Key elements:
+- **Interactive execution**: Uses a dedicated interactive spawner with `stdin: 'pipe'` so LLDB commands can be streamed across multiple tool calls.
+- **Session manager**: Tracks debug session metadata (session id, simulator id, pid, timestamps) and maintains a “current” session.
+- **Backend abstraction**: `DebuggerBackend` keeps the tool contract stable while allowing future DAP support.
+
 ### MCP Resources System
 
 XcodeBuildMCP provides dual interfaces: traditional MCP tools and efficient MCP resources for supported clients. Resources are located in `src/mcp/resources/` and are automatically discovered **at build time**. The build process generates `src/core/generated-resources.ts`, which contains dynamic loaders for each resource, improving startup performance. For more details on creating resources, see the [Plugin Development Guide](docs/PLUGIN_DEVELOPMENT.md).
@@ -432,7 +441,7 @@ describe('Tool Name', () => {
 
     // 2. Call the tool's logic function, injecting the mock executor
     const result = await someToolLogic({ requiredParam: 'value' }, mockExecutor);
-    
+
     // 3. Assert the final result
     expect(result).toEqual({
       content: [{ type: 'text', text: 'Expected output' }],

docs/ARCHITECTURE.md

@@ -0,0 +1,277 @@
+# Debugging Architecture
+
+This document describes how the simulator debugging tools are wired, how sessions are managed,
+and how external tools (simctl, Simulator, LLDB, xcodebuild) are invoked.
+
+## Scope
+
+- Tools: `src/mcp/tools/debugging/*`
+- Debugger subsystem: `src/utils/debugger/*`
+- Execution and tool wiring: `src/utils/typed-tool-factory.ts`, `src/utils/execution/*`
+- External invocation: `xcrun simctl`, `xcrun lldb`, `xcodebuild`
+
+## Registration and Wiring
+
+- Workflow discovery is automatic: `src/core/plugin-registry.ts` loads debugging tools via the
+  generated workflow loaders (`src/core/generated-plugins.ts`).
+- Tool handlers are created with the typed tool factory:
+  - `createTypedToolWithContext` for standard tools (Zod validation + dependency injection).
+  - `createSessionAwareToolWithContext` for session-aware tools (merges session defaults and
+    validates requirements).
+- Debugging tools inject a `DebuggerToolContext` that provides:
+  - `executor`: a `CommandExecutor` used for simctl and other command execution.
+  - `debugger`: a shared `DebuggerManager` instance.
+
+## Session Defaults and Validation
+
+- Session defaults live in `src/utils/session-store.ts` and are merged with user args by the
+  session-aware tool factory.
+- `debug_attach_sim` is session-aware; it can omit `simulatorId`/`simulatorName` in the public
+  schema and rely on session defaults.
+- The `XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS` env flag exposes legacy schemas that include all
+  parameters (no session default hiding).
+
+## Debug Session Lifecycle
+
+`DebuggerManager` owns lifecycle, state, and backend routing:
+
+Backend selection happens inside `DebuggerManager.createSession`:
+
+- Selection order: explicit `backend` argument -> `XCODEBUILDMCP_DEBUGGER_BACKEND` -> default `lldb-cli`.
+- Env values: `lldb-cli`/`lldb` -> `lldb-cli`, `dap` -> `dap`, anything else throws.
+- Backend factory: `defaultBackendFactory` maps `lldb-cli` to `createLldbCliBackend` and `dap` to
+  `createDapBackend`. A custom factory can be injected for tests or extensions.
+
+1. `debug_attach_sim` resolves simulator UUID and PID, then calls
+   `DebuggerManager.createSession`.
+2. `DebuggerManager` creates a backend (default `lldb-cli`), attaches to the process, and stores
+   session metadata (id, simulatorId, pid, timestamps).
+3. Debugging tools (`debug_lldb_command`, `debug_stack`, `debug_variables`,
+   `debug_breakpoint_add/remove`) look up the session (explicit id or current) and route commands
+   to the backend.
+4. `debug_detach` calls `DebuggerManager.detachSession` to detach and dispose the backend.
+
+## Debug Session + Command Execution Flow
+
+Session lifecycle flow (text):
+
+1. Client calls `debug_attach_sim`.
+2. `debug_attach_sim` resolves simulator UUID and PID, then calls `DebuggerManager.createSession`.
+3. `DebuggerManager.createSession` resolves backend kind (explicit/env/default), instantiates the
+   backend, and calls `backend.attach`.
+4. Command tools (`debug_lldb_command`, `debug_stack`, `debug_variables`) call
+   `DebuggerManager.runCommand`/`getStack`/`getVariables`, which route to the backend.
+5. `debug_detach` calls `DebuggerManager.detachSession`, which invokes `backend.detach` and
+   `backend.dispose`.
+
+`LldbCliBackend.runCommand()` flow (text):
+
+1. Enqueue the command to serialize LLDB access.
+2. Await backend readiness (`initialize` completed).
+3. Write the command to the interactive process.
+4. Write `script print("__XCODEBUILDMCP_DONE__")` to emit the sentinel marker.
+5. Buffer stdout/stderr until the sentinel is detected.
+6. Trim the buffer to the next prompt, sanitize output, and return the result.
+
+<details>
+<summary>Sequence diagrams (Mermaid)</summary>
+
+```mermaid
+sequenceDiagram
+  participant U as User/Client
+  participant A as debug_attach_sim
+  participant M as DebuggerManager
+  participant F as backendFactory
+  participant B as DebuggerBackend (lldb-cli|dap)
+  participant L as LldbCliBackend
+  participant P as InteractiveProcess (xcrun lldb)
+
+  U->>A: debug_attach_sim(simulator*, bundleId|pid)
+  A->>A: determineSimulatorUuid(...)
+  A->>A: resolveSimulatorAppPid(...) (if bundleId)
+  A->>M: createSession({simulatorId, pid, waitFor})
+  M->>M: resolveBackendKind(explicit/env/default)
+  M->>F: create backend(kind)
+  F-->>M: backend instance
+  M->>B: attach({pid, simulatorId, waitFor})
+  alt kind == lldb-cli
+    B-->>L: (is LldbCliBackend)
+    L->>P: spawn xcrun lldb + initialize prompt/sentinel
+  else kind == dap
+    B-->>M: throws DAP_ERROR_MESSAGE
+  end
+  M-->>A: DebugSessionInfo {id, backend, ...}
+  A->>M: setCurrentSession(id) (optional)
+  U->>M: runCommand(id?, "thread backtrace")
+  M->>B: runCommand(...)
+  U->>M: detachSession(id?)
+  M->>B: detach()
+  M->>B: dispose()
+```
+
+```mermaid
+sequenceDiagram
+  participant T as debug_lldb_command
+  participant M as DebuggerManager
+  participant L as LldbCliBackend
+  participant P as InteractiveProcess
+  participant S as stdout/stderr buffer
+
+  T->>M: runCommand(sessionId?, command, {timeoutMs?})
+  M->>L: runCommand(command)
+  L->>L: enqueue(work)
+  L->>L: await ready (initialize())
+  L->>P: write(command + "\n")
+  L->>P: write('script print("__XCODEBUILDMCP_DONE__")\n')
+  P-->>S: stdout/stderr chunks
+  S-->>L: handleData() appends to buffer
+  L->>L: checkPending() finds sentinel
+  L->>L: slice output up to sentinel
+  L->>L: trim buffer to next prompt (if present)
+  L->>L: sanitizeOutput() + trimEnd()
+  L-->>M: output string
+  M-->>T: output string
+```
+
+</details>
+
+## LLDB CLI Backend (Default)
+
+- Backend implementation: `src/utils/debugger/backends/lldb-cli-backend.ts`.
+- Uses `InteractiveSpawner` from `src/utils/execution/interactive-process.ts` to keep a single
+  long-lived `xcrun lldb` process alive.
+- Keeps LLDB state (breakpoints, selected frames, target) across tool calls without reattaching.
+
+### Internals: interactive process model
+
+- The backend spawns `xcrun lldb --no-lldbinit -o "settings set prompt <prompt>"`.
+- `InteractiveProcess.write()` is used to send commands; stdout and stderr are merged into a single
+  parse buffer.
+- `InteractiveProcess.dispose()` closes stdin, removes listeners, and kills the process.
+
+### Prompt and sentinel protocol
+
+The backend uses a prompt + sentinel protocol to detect command completion reliably:
+
+- `LLDB_PROMPT = "XCODEBUILDMCP_LLDB> "`
+- `COMMAND_SENTINEL = "__XCODEBUILDMCP_DONE__"`
+
+Definitions:
+
+- Prompt: the LLDB REPL prompt string that indicates LLDB is ready to accept the next command.
+- Sentinel: a unique marker explicitly printed after each command to mark the end of that
+  command's output.
+
+Protocol flow:
+
+1. Startup: write `script print("__XCODEBUILDMCP_DONE__")` to prime the prompt parser.
+2. For each command:
+   - Write the command.
+   - Write `script print("__XCODEBUILDMCP_DONE__")`.
+   - Read until the sentinel is observed, then trim up to the next prompt.
+
+The sentinel marks command completion, while the prompt indicates the REPL is ready for the next
+command.
+
+Why both a prompt and a sentinel?
+
+- The sentinel is the explicit end-of-output marker; LLDB does not provide a reliable boundary for
+  arbitrary command output otherwise.
+- The prompt is used to cleanly align the buffer for the next command after the sentinel is seen.
+
+Annotated example (simplified):
+
+1. Backend writes:
+   - `thread backtrace`
+   - `script print("__XCODEBUILDMCP_DONE__")`
+2. LLDB emits (illustrative):
+   - `... thread backtrace output ...`
+   - `__XCODEBUILDMCP_DONE__`
+   - `XCODEBUILDMCP_LLDB> `
+3. Parser behavior:
+   - Sentinel marks the end of the command output payload.
+   - Prompt is used to trim the buffer so the next command starts cleanly.
+
+### Output parsing and sanitization
+
+- `handleData()` appends to an internal buffer, and `checkPending()` scans for the sentinel regex
+  `/(^|\\r?\\n)__XCODEBUILDMCP_DONE__(\\r?\\n)/`.
+- Output is the buffer up to the sentinel. The remainder is trimmed to the next prompt if present.
+- `sanitizeOutput()` removes prompt echoes, sentinel lines, the `script print(...)` lines, and empty
+  lines, then `runCommand()` returns `trimEnd()` output.
+
+### Concurrency model (queueing)
+
+- Commands are serialized through a promise queue to avoid interleaved output.
+- `waitForSentinel()` rejects if a pending command exists, acting as a safety check.
+
+### Timeouts, errors, and disposal
+
+- Startup timeout: `DEFAULT_STARTUP_TIMEOUT_MS = 10_000`.
+- Per-command timeout: `DEFAULT_COMMAND_TIMEOUT_MS = 30_000` (override via `runCommand` opts).
+- Timeout failure clears the pending command and rejects the promise.
+- `assertNoLldbError()` throws if `/error:/i` appears in output (simple heuristic).
+- Process exit triggers `failPending(new Error(...))` so in-flight calls fail promptly.
+- `runCommand()` rejects immediately if the backend is already disposed.
+
+### Testing and injection
+
+`getDefaultInteractiveSpawner()` throws in test environments to prevent spawning real interactive
+processes. Tests should inject a mock `InteractiveSpawner` into `createLldbCliBackend()` or a custom
+`DebuggerManager` backend factory.
+
+## DAP Backend (Stub / Not Implemented)
+
+- Implementation: `src/utils/debugger/backends/dap-backend.ts`.
+- Selected via backend selection (explicit `backend`, `XCODEBUILDMCP_DEBUGGER_BACKEND=dap`).
+- Current status: not implemented. All `DebuggerBackend` methods throw `DAP_ERROR_MESSAGE`,
+  including `dispose()`.
+
+Practical effect:
+
+- Setting `XCODEBUILDMCP_DEBUGGER_BACKEND=dap` causes `debug_attach_sim` to fail during
+  session creation because `backend.attach()` throws.
+- `DebuggerManager.createSession` attempts to call `dispose()` on failure, but the stub `dispose()`
+  also throws (same message). This is expected until a real DAP backend exists.
+
+Use `lldb-cli` (default) for actual debugging.
+
+## External Tool Invocation
+
+### simctl and Simulator
+
+- Simulator UUID resolution uses `xcrun simctl list devices available -j`
+  (`determineSimulatorUuid` in `src/utils/simulator-utils.ts`).
+- PID lookup uses `xcrun simctl spawn <simulatorId> launchctl list`
+  (`resolveSimulatorAppPid` in `src/utils/debugger/simctl.ts`).
+
+### LLDB
+
+- Attachment uses `xcrun lldb --no-lldbinit` in the interactive backend.
+- Breakpoint conditions are applied by issuing an additional LLDB command:
+  `breakpoint modify -c "<condition>" <id>`.
+
+### xcodebuild (Build/Launch Context)
+
+- Debugging assumes a running simulator app.
+- The typical flow is build and launch via simulator tools (for example `build_sim`),
+  which uses `executeXcodeBuildCommand` to invoke `xcodebuild` (or `xcodemake` when enabled).
+- After launch, `debug_attach_sim` attaches LLDB to the simulator process.
+
+## Typical Tool Flow
+
+1. Build and launch the app on a simulator (`build_sim`, `launch_app_sim`).
+2. Attach LLDB (`debug_attach_sim`) using session defaults or explicit simulator + bundle ID.
+3. Set breakpoints (`debug_breakpoint_add`), inspect stack/variables (`debug_stack`,
+   `debug_variables`), and issue arbitrary LLDB commands (`debug_lldb_command`).
+4. Detach when done (`debug_detach`).
+
+## Integration Points Summary
+
+- Tool entrypoints: `src/mcp/tools/debugging/*`
+- Session defaults: `src/utils/session-store.ts`
+- Debug session manager: `src/utils/debugger/debugger-manager.ts`
+- Backends: `src/utils/debugger/backends/lldb-cli-backend.ts` (default),
+  `src/utils/debugger/backends/dap-backend.ts` (stub)
+- Interactive execution: `src/utils/execution/interactive-process.ts` (used by LLDB CLI backend)
+- External commands: `xcrun simctl`, `xcrun lldb`, `xcodebuild`

docs/DEBUGGING_ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # XcodeBuildMCP Tools Reference
 
-XcodeBuildMCP provides 63 tools organized into 12 workflow groups for comprehensive Apple development workflows.
+XcodeBuildMCP provides 70 tools organized into 13 workflow groups for comprehensive Apple development workflows.
 
 ## Workflow Groups
 
@@ -68,6 +68,16 @@ XcodeBuildMCP provides 63 tools organized into 12 workflow groups for comprehens
 - `session_clear_defaults` - Clear selected or all session defaults.
 - `session_set_defaults` - Set the session defaults needed by many tools. Most tools require one or more session defaults to be set before they can be used. Agents should set all relevant defaults up front in a single call (e.g., project/workspace, scheme, simulator or device ID, useLatestOS) to avoid iterative prompts; only set the keys your workflow needs.
 - `session_show_defaults` - Show current session defaults.
+### Simulator Debugging (`debugging`)
+**Purpose**: Interactive iOS Simulator debugging tools: attach LLDB, manage breakpoints, inspect stack/variables, and run LLDB commands. (7 tools)
+
+- `debug_attach_sim` - Attach LLDB to a running iOS simulator app. Provide bundleId or pid, plus simulator defaults.
+- `debug_breakpoint_add` - Add a breakpoint by file/line or function name for the active debug session.
+- `debug_breakpoint_remove` - Remove a breakpoint by id for the active debug session.
+- `debug_detach` - Detach the current debugger session or a specific debugSessionId.
+- `debug_lldb_command` - Run an arbitrary LLDB command within the active debug session.
+- `debug_stack` - Return a thread backtrace from the active debug session.
+- `debug_variables` - Return variables for a selected frame in the active debug session.
 ### Simulator Management (`simulator-management`)
 **Purpose**: Tools for managing simulators from booting, opening simulators, listing simulators, stopping simulators, erasing simulator content and settings, and setting simulator environment options like location, network, statusbar and appearance. (5 tools)
 
@@ -93,7 +103,7 @@ XcodeBuildMCP provides 63 tools organized into 12 workflow groups for comprehens
 **Purpose**: UI automation and accessibility testing tools for iOS simulators. Perform gestures, interactions, screenshots, and UI analysis for automated testing workflows. (11 tools)
 
 - `button` - Press hardware button on iOS simulator. Supported buttons: apple-pay, home, lock, side-button, siri
-- `describe_ui` - Gets entire view hierarchy with precise frame coordinates (x, y, width, height) for all visible elements. Use this before UI interactions or after layout changes - do NOT guess coordinates from screenshots. Returns JSON tree with frame data for accurate automation.
+- `describe_ui` - Gets entire view hierarchy with precise frame coordinates (x, y, width, height) for all visible elements. Use this before UI interactions or after layout changes - do NOT guess coordinates from screenshots. Returns JSON tree with frame data for accurate automation. Requires the target process to be running; paused debugger/breakpoints can yield an empty tree.
 - `gesture` - Perform gesture on iOS simulator using preset gestures: scroll-up, scroll-down, scroll-left, scroll-right, swipe-from-left-edge, swipe-from-right-edge, swipe-from-top-edge, swipe-from-bottom-edge
 - `key_press` - Press a single key by keycode on the simulator. Common keycodes: 40=Return, 42=Backspace, 43=Tab, 44=Space, 58-67=F1-F10.
 - `key_sequence` - Press key sequence using HID keycodes on iOS simulator with configurable delay
@@ -106,9 +116,9 @@ XcodeBuildMCP provides 63 tools organized into 12 workflow groups for comprehens
 
 ## Summary Statistics
 
-- **Total Tools**: 63 canonical tools + 22 re-exports = 85 total
-- **Workflow Groups**: 12
+- **Total Tools**: 70 canonical tools + 22 re-exports = 92 total
+- **Workflow Groups**: 13
 
 ---
 
-*This documentation is automatically generated by `scripts/update-tools-docs.ts` using static analysis. Last updated: 2025-12-30*
+*This documentation is automatically generated by `scripts/update-tools-docs.ts` using static analysis. Last updated: 2026-01-02*