debug

Instructions

Implementation Reference

• src/handlers/debug.ts:6-24 (handler)

  The handleDebugCommands function in src/handlers/debug.ts handles the 'debug' tool (and other debug session commands). The 'debug' case (lines 8-24) starts a debug session for a Go package using startDebugSession.

  export async function handleDebugCommands(name: string, args: any) {
    switch (name) {
      case "debug": {
        const pkg = (args?.package as string) || ".";
        const buildFlags = args?.buildFlags as string | undefined;
        const cmdArgs: string[] = [];
        
        if (buildFlags) {
          cmdArgs.push("--build-flags", buildFlags);
        }
  
        const session = await startDebugSession("debug", pkg, cmdArgs);
        return {
          content: [{
            type: "text",
            text: `Started debug session ${session.id} for package ${pkg}`
          }]
        };
      }

• src/server.ts:68-84 (schema)

  The input schema for the 'debug' tool is defined in the ListToolsRequestSchema handler in src/server.ts, lines 69-84. It defines a tool named 'debug' with optional 'package' and 'buildFlags' string parameters.

  {
    name: "debug",
    description: "Start debugging a Go package",
    inputSchema: {
      type: "object",
      properties: {
        package: {
          type: "string",
          description: "Package to debug (defaults to current directory)"
        },
        buildFlags: {
          type: "string",
          description: "Build flags to pass to the compiler"
        }
      }
    }
  },

• src/server.ts:402-408 (registration)

  The 'debug' tool is registered via the CallToolRequestSchema handler in src/server.ts. Line 406 checks if the tool name is 'debug' (among others) and routes to handleDebugCommands.

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    const { name, arguments: args } = request.params;
  
    // Debug commands
    if (["debug", "attach", "exec", "test", "core", "dap", "replay", "trace"].includes(name)) {
      return handleDebugCommands(name, args);
    }

• src/session.ts:35-64 (helper)

  The startDebugSession function in src/session.ts is a helper that spawns a dlv process in headless mode and creates a DebugSession object. It is used by the 'debug' handler.

  export async function startDebugSession(type: string, target: string, args: string[] = []): Promise<DebugSession> {
    const port = await getAvailablePort();
    const id = Math.random().toString(36).substring(7);
    
    const dlvArgs = [
      type,
      "--headless",
      `--listen=:${port}`,
      "--accept-multiclient",
      "--api-version=2",
      target,
      ...args
    ];
  
    const process = spawn("dlv", dlvArgs, {
      stdio: ["pipe", "pipe", "pipe"]
    });
  
    const session: DebugSession = {
      id,
      type,
      target,
      process,
      port,
      breakpoints: new Map()
    };
  
    sessions.set(id, session);
    return session;
  }

• src/types.ts:16-25 (helper)

  The DebugSession interface in src/types.ts defines the structure used for debug sessions, including the type field which can be 'debug'.

  export interface DebugSession {
    id: string;
    type: string; // 'debug' | 'attach' | 'exec' | 'test' | 'core' | 'replay' | 'trace' | 'dap'
    target: string;
    process?: ChildProcess;
    port: number;
    breakpoints: Map<number, Breakpoint>;
    logOutput?: string[];
    backend?: string;
  }