DAP backend

Author: cameroncooke

.smithery/index.cjs

@@ -220,21 +220,20 @@ Annotated example (simplified):
 processes. Tests should inject a mock `InteractiveSpawner` into `createLldbCliBackend()` or a custom
 `DebuggerManager` backend factory.
 
-## DAP Backend (Stub / Not Implemented)
+## DAP Backend (lldb-dap)
 
-- Implementation: `src/utils/debugger/backends/dap-backend.ts`.
+- Implementation: `src/utils/debugger/backends/dap-backend.ts`, with protocol support in
+  `src/utils/debugger/dap/transport.ts`, `src/utils/debugger/dap/types.ts`, and adapter discovery in
+  `src/utils/debugger/dap/adapter-discovery.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.
+- Adapter discovery uses `xcrun --find lldb-dap`; missing adapters raise a clear dependency error.
+- One `lldb-dap` process is spawned per session; DAP framing and request correlation are handled
+  by `DapTransport`.
+- Session handshake: `initialize` → `attach` → `configurationDone`.
+- Breakpoints are stateful: adding/removing re-issues `setBreakpoints` or
+  `setFunctionBreakpoints` with the remaining list. Conditions are passed in the request body.
+- Stack/variables typically require a stopped thread; the backend returns guidance if the process
+  is still running.
 
 ## External Tool Invocation
 
@@ -248,8 +247,8 @@ Use `lldb-cli` (default) for actual debugging.
 ### 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>`.
+- Breakpoint conditions are applied internally by the LLDB CLI backend using
+  `breakpoint modify -c "<condition>" <id>` after creation.
 
 ### xcodebuild (Build/Launch Context)
 
@@ -272,6 +271,6 @@ Use `lldb-cli` (default) for actual 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)
+  `src/utils/debugger/backends/dap-backend.ts`
 - Interactive execution: `src/utils/execution/interactive-process.ts` (used by LLDB CLI backend)
 - External commands: `xcrun simctl`, `xcrun lldb`, `xcodebuild`

docs/DAP_BACKEND_IMPLEMENTATION_PLAN.md

@@ -36,11 +36,6 @@ const debugBreakpointAddSchema = z.preprocess(
 
 export type DebugBreakpointAddParams = z.infer<typeof debugBreakpointAddSchema>;
 
-function formatCondition(condition: string): string {
-  const escaped = condition.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-  return `"${escaped}"`;
-}
-
 export async function debug_breakpoint_addLogic(
   params: DebugBreakpointAddParams,
   ctx: DebuggerToolContext,
@@ -54,12 +49,9 @@ export async function debug_breakpoint_addLogic(
       return createErrorResponse('Invalid breakpoint', 'file and line are required.');
     }
 
-    const result = await ctx.debugger.addBreakpoint(params.debugSessionId, spec);
-
-    if (params.condition) {
-      const conditionCommand = `breakpoint modify -c ${formatCondition(params.condition)} ${result.id}`;
-      await ctx.debugger.runCommand(params.debugSessionId, conditionCommand);
-    }
+    const result = await ctx.debugger.addBreakpoint(params.debugSessionId, spec, {
+      condition: params.condition,
+    });
 
     return createTextResponse(`✅ Breakpoint ${result.id} set.\n\n${result.rawOutput.trim()}`);
   } catch (error) {

docs/DEBUGGING_ARCHITECTURE.md

@@ -24,6 +24,15 @@ const doctorSchema = z.object({
 // Use z.infer for type safety
 type DoctorParams = z.infer<typeof doctorSchema>;
 
+async function checkLldbDapAvailability(executor: CommandExecutor): Promise<boolean> {
+  try {
+    const result = await executor(['xcrun', '--find', 'lldb-dap'], 'Check lldb-dap');
+    return result.success && result.output.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Run the doctor tool and return the results
  */
@@ -52,6 +61,9 @@ export async function runDoctor(
   const xcodemakeEnabled = deps.features.isXcodemakeEnabled();
   const xcodemakeAvailable = await deps.features.isXcodemakeAvailable();
   const makefileExists = deps.features.doesMakefileExist('./');
+  const lldbDapAvailable = await checkLldbDapAvailability(deps.commandExecutor);
+  const selectedDebuggerBackend = process.env.XCODEBUILDMCP_DEBUGGER_BACKEND?.trim();
+  const dapSelected = selectedDebuggerBackend?.toLowerCase() === 'dap';
 
   const doctorInfo = {
     serverVersion: version,
@@ -75,6 +87,12 @@ export async function runDoctor(
         running_under_mise: Boolean(process.env.XCODEBUILDMCP_RUNNING_UNDER_MISE),
         available: binaryStatus['mise'].available,
       },
+      debugger: {
+        dap: {
+          available: lldbDapAvailable,
+          selected: selectedDebuggerBackend ?? '(default lldb-cli)',
+        },
+      },
     },
     pluginSystem: pluginSystemInfo,
   } as const;
@@ -196,6 +214,15 @@ export async function runDoctor(
     `- Running under mise: ${doctorInfo.features.mise.running_under_mise ? '✅ Yes' : '❌ No'}`,
     `- Mise available: ${doctorInfo.features.mise.available ? '✅ Yes' : '❌ No'}`,
 
+    `\n### Debugger Backend (DAP)`,
+    `- lldb-dap available: ${doctorInfo.features.debugger.dap.available ? '✅ Yes' : '❌ No'}`,
+    `- Selected backend: ${doctorInfo.features.debugger.dap.selected}`,
+    ...(dapSelected && !lldbDapAvailable
+      ? [
+          `- Warning: DAP backend selected but lldb-dap not available. Set XCODEBUILDMCP_DEBUGGER_BACKEND=lldb-cli to use the CLI backend.`,
+        ]
+      : []),
+
     `\n### Available Tools`,
     `- Total Plugins: ${'totalPlugins' in doctorInfo.pluginSystem ? doctorInfo.pluginSystem.totalPlugins : 0}`,
     `- Plugin Directories: ${'pluginDirectories' in doctorInfo.pluginSystem ? doctorInfo.pluginSystem.pluginDirectories : 0}`,

src/mcp/tools/debugging/debug_breakpoint_add.ts

@@ -87,6 +87,7 @@ export interface FeatureDetector {
 }
 
 export interface DoctorDependencies {
+  commandExecutor: CommandExecutor;
   binaryChecker: BinaryChecker;
   xcode: XcodeInfoProvider;
   env: EnvironmentInfoProvider;
@@ -96,6 +97,7 @@ export interface DoctorDependencies {
 }
 
 export function createDoctorDependencies(executor: CommandExecutor): DoctorDependencies {
+  const commandExecutor = executor;
   const binaryChecker: BinaryChecker = {
     async checkBinaryAvailability(binary: string) {
       // If bundled axe is available, reflect that in dependencies even if not on PATH
@@ -276,7 +278,7 @@ export function createDoctorDependencies(executor: CommandExecutor): DoctorDepen
     doesMakefileExist,
   };
 
-  return { binaryChecker, xcode, env, plugins, runtime, features };
+  return { commandExecutor, binaryChecker, xcode, env, plugins, runtime, features };
 }
 
 export type { CommandExecutor };

src/mcp/tools/doctor/doctor.ts

@@ -16,8 +16,11 @@
  */
 
 import { ChildProcess } from 'child_process';
+import { EventEmitter } from 'node:events';
+import { PassThrough } from 'node:stream';
 import { CommandExecutor } from '../utils/CommandExecutor.ts';
 import { FileSystemExecutor } from '../utils/FileSystemExecutor.ts';
+import type { InteractiveProcess, InteractiveSpawner } from '../utils/execution/index.ts';
 
 /**
  * Create a mock executor for testing
@@ -159,6 +162,100 @@ export function createCommandMatchingMockExecutor(
   };
 }
 
+export type MockInteractiveSession = {
+  stdout: PassThrough;
+  stderr: PassThrough;
+  stdin: PassThrough;
+  emitExit: (code?: number | null, signal?: NodeJS.Signals | null) => void;
+  emitError: (error: Error) => void;
+};
+
+export type MockInteractiveSpawnerScript = {
+  onSpawn?: (session: MockInteractiveSession) => void;
+  onWrite?: (data: string, session: MockInteractiveSession) => void;
+  onKill?: (signal: NodeJS.Signals | undefined, session: MockInteractiveSession) => void;
+  onDispose?: (session: MockInteractiveSession) => void;
+};
+
+export function createMockInteractiveSpawner(
+  script: MockInteractiveSpawnerScript = {},
+): InteractiveSpawner {
+  return (): InteractiveProcess => {
+    const stdout = new PassThrough();
+    const stderr = new PassThrough();
+    const stdin = new PassThrough();
+    const emitter = new EventEmitter();
+    const mockProcess = emitter as unknown as ChildProcess;
+    const mutableProcess = mockProcess as unknown as {
+      stdout: PassThrough | null;
+      stderr: PassThrough | null;
+      stdin: PassThrough | null;
+      killed: boolean;
+      exitCode: number | null;
+      signalCode: NodeJS.Signals | null;
+      spawnargs: string[];
+      spawnfile: string;
+      pid: number;
+    };
+
+    mutableProcess.stdout = stdout;
+    mutableProcess.stderr = stderr;
+    mutableProcess.stdin = stdin;
+    mutableProcess.killed = false;
+    mutableProcess.exitCode = null;
+    mutableProcess.signalCode = null;
+    mutableProcess.spawnargs = [];
+    mutableProcess.spawnfile = 'mock';
+    mutableProcess.pid = 12345;
+    mockProcess.kill = ((signal?: NodeJS.Signals): boolean => {
+      mutableProcess.killed = true;
+      emitter.emit('exit', 0, signal ?? null);
+      return true;
+    }) as ChildProcess['kill'];
+
+    const session: MockInteractiveSession = {
+      stdout,
+      stderr,
+      stdin,
+      emitExit: (code = 0, signal = null) => {
+        emitter.emit('exit', code, signal);
+      },
+      emitError: (error) => {
+        emitter.emit('error', error);
+      },
+    };
+
+    script.onSpawn?.(session);
+
+    let disposed = false;
+
+    return {
+      process: mockProcess,
+      write(data: string): void {
+        if (disposed) {
+          throw new Error('Mock interactive process disposed');
+        }
+        script.onWrite?.(data, session);
+      },
+      kill(signal?: NodeJS.Signals): void {
+        if (disposed) return;
+        mutableProcess.killed = true;
+        script.onKill?.(signal, session);
+        emitter.emit('exit', 0, signal ?? null);
+      },
+      dispose(): void {
+        if (disposed) return;
+        disposed = true;
+        script.onDispose?.(session);
+        stdout.end();
+        stderr.end();
+        stdin.end();
+        emitter.removeAllListeners();
+      },
+    };
+  };
+}
+
 /**
  * Create a mock file system executor for testing
  */

src/mcp/tools/doctor/lib/doctor.deps.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest';
+
+import type { BreakpointInfo, BreakpointSpec } from '../types.ts';
+import type { DebuggerBackend } from '../backends/DebuggerBackend.ts';
+import { DebuggerManager } from '../debugger-manager.ts';
+
+function createBackend(overrides: Partial<DebuggerBackend> = {}): DebuggerBackend {
+  const base: DebuggerBackend = {
+    kind: 'dap',
+    attach: async () => {},
+    detach: async () => {},
+    runCommand: async () => '',
+    addBreakpoint: async (spec: BreakpointSpec): Promise<BreakpointInfo> => ({
+      id: 1,
+      spec,
+      rawOutput: '',
+    }),
+    removeBreakpoint: async () => '',
+    getStack: async () => '',
+    getVariables: async () => '',
+    dispose: async () => {},
+  };
+
+  return { ...base, ...overrides };
+}
+
+describe('DebuggerManager DAP selection', () => {
+  it('selects dap backend when env is set', async () => {
+    const prevEnv = process.env.XCODEBUILDMCP_DEBUGGER_BACKEND;
+    process.env.XCODEBUILDMCP_DEBUGGER_BACKEND = 'dap';
+
+    let selected: string | null = null;
+    const backend = createBackend({ kind: 'dap' });
+    const manager = new DebuggerManager({
+      backendFactory: async (kind) => {
+        selected = kind;
+        return backend;
+      },
+    });
+
+    await manager.createSession({ simulatorId: 'sim-1', pid: 1000 });
+
+    expect(selected).toBe('dap');
+
+    if (prevEnv === undefined) {
+      delete process.env.XCODEBUILDMCP_DEBUGGER_BACKEND;
+    } else {
+      process.env.XCODEBUILDMCP_DEBUGGER_BACKEND = prevEnv;
+    }
+  });
+
+  it('disposes backend when attach fails without masking error', async () => {
+    const error = new Error('attach failed');
+    let disposeCalled = false;
+
+    const backend = createBackend({
+      attach: async () => {
+        throw error;
+      },
+      dispose: async () => {
+        disposeCalled = true;
+        throw new Error('dispose failed');
+      },
+    });
+
+    const manager = new DebuggerManager({
+      backendFactory: async () => backend,
+    });
+
+    await expect(
+      manager.createSession({ simulatorId: 'sim-1', pid: 2000, backend: 'dap' }),
+    ).rejects.toThrow('attach failed');
+    expect(disposeCalled).toBe(true);
+  });
+});

src/test-utils/mock-executors.ts

@@ -8,7 +8,7 @@ export interface DebuggerBackend {
 
   runCommand(command: string, opts?: { timeoutMs?: number }): Promise<string>;
 
-  addBreakpoint(spec: BreakpointSpec): Promise<BreakpointInfo>;
+  addBreakpoint(spec: BreakpointSpec, opts?: { condition?: string }): Promise<BreakpointInfo>;
   removeBreakpoint(id: number): Promise<string>;
 
   getStack(opts?: { threadIndex?: number; maxFrames?: number }): Promise<string>;