plan.md•9.07 kB
# Implementation Plan: Watchtower DAP Windows Debugging
**Branch**: `001-dap-windows-debug` | **Date**: 2025-10-17 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/001-dap-windows-debug/spec.md`
## Summary
Watchtower DAP Windows Debugging implements a Windows-native MCP ⇄ DAP bridge enabling step-through debugging for C#, Node/TS, Python, and Dart. The solution uses Node.js 22 + TypeScript with MCP server architecture, DAP client per session, stdio transport by default (TCP only for explicit attach), and supports 13 MCP tools including event polling. The plan aligns with constitution principles: Windows-native only, DAP as single source of truth, minimal MCP tool surface, stdio-first transport, deterministic debug loop, security-by-default, and observability foundation.
## Technical Context
**Language/Version**: Node.js 22 LTS (Windows x64), TypeScript
**Primary Dependencies**: @modelcontextprotocol/sdk, vscode-jsonrpc, @vscode/debugprotocol, zod, execa, commander, pino, opentelemetry-sdk-node, esbuild, vitest
**Storage**: N/A (stateless debugging sessions)
**Testing**: vitest for unit/integration tests, manual testing with sample projects
**Target Platform**: Windows 10, Windows 11 (headless MCP tools only)
**Project Type**: Single project MCP server
**Performance Goals**: Time to first break ≤ 1000ms, step operations ≤ 200ms (95th percentile), event buffers handle 100+ events/second
**Constraints**: <200ms p95 for stepping, redact env/args in logs, bounded event buffers with pagination, no arbitrary FS access
**Scale/Scope**: 4 target languages, 13 MCP tools, per-session ring buffers, Windows CI integration
## Constitution Check
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
✅ **Windows-Native Focus**: Implementation uses Windows-specific adapters (vsdbg, netcoredbg, vscode-js-debug, debugpy, dart debug_adapter) with no Linux/WSL support
✅ **DAP as Single Source of Truth**: All debugging operations flow through DAP adapters; MCP tools interface directly with DAP protocol
✅ **Minimal MCP Tool Surface**: 13 essential tools covering core debugging operations (start, breakpoints, stepping, variables, events)
✅ **Stdio-First Transport**: Default stdio transport; TCP only for explicit attach scenarios
✅ **Deterministic Debug Loop**: Event polling with ring buffer ensures predictable state transitions for agents
✅ **Security-By-Default**: Redact env/args, limited FS access, 'watchtower doctor' diagnostic tool
✅ **Observability Foundation**: OpenTelemetry metrics, pino logging, structured events
✅ **Performance Targets**: TFFB ≤ 1000ms, STEP_p95 ≤ 200ms, event buffer capacity ≥ 100 events/sec
✅ **Compatibility**: Supports Windows 10/11, Node.js 22.x/.NET 8.x/Python 3.11+/Dart 3.x
✅ **Operational Constraints**: Headless only, no remote Linux, bounded buffers with pagination
## Project Structure
### Documentation (this feature)
```
specs/001-dap-windows-debug/
├── plan.md # This file (/speckit.plan command output)
├── research.md # Phase 0 output (/speckit.plan command)
├── data-model.md # Phase 1 output (/speckit.plan command)
├── quickstart.md # Phase 1 output (/speckit.plan command)
├── contracts/ # Phase 1 output (/speckit.plan command)
└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
```
### Source Code (repository root)
```
src/
├── server/
│ ├── mcp-server.ts # MCP server implementation
│ ├── session-manager.ts # Session lifecycle management
│ ├── transport/ # Transport layer (stdio/tcp)
│ └── router.ts # Tool routing and request handling
├── adapters/
│ ├── base-adapter.ts # Base adapter interface
│ ├── csharp-adapter.ts # C# adapter (vsdbg/netcoredbg)
│ ├── node-adapter.ts # Node.js adapter (vscode-js-debug)
│ ├── python-adapter.ts # Python adapter (debugpy)
│ └── dart-adapter.ts # Dart adapter (dart/flutter dap)
├── protocol/
│ ├── dap-client.ts # DAP protocol client
│ ├── event-buffer.ts # Ring buffer for event polling
│ └── types.ts # TypeScript types and schemas
├── tools/
│ ├── start.ts # dap.start tool implementation
│ ├── breakpoints.ts # dap.setBreakpoints tool implementation
│ ├── stepping.ts # dap.continue, dap.pause, dap.step tools
│ ├── threads.ts # dap.threads tool implementation
│ ├── stack.ts # dap.stackTrace, dap.scopes, dap.variables
│ ├── evaluate.ts # dap.evaluate tool implementation
│ ├── events.ts # dap.events.poll implementation
│ └── session.ts # dap.terminate, dap.disconnect
├── security/
│ ├── redactor.ts # Environment/sensitive data redaction
│ └── validator.ts # Input validation and path restrictions
├── metrics/
│ ├── metrics.ts # OpenTelemetry metrics setup
│ └── traces.ts # Distributed tracing
├── diagnostics/
│ ├── doctor.ts # 'watchtower doctor' diagnostic tool
│ └── health.ts # Health check endpoints
├── cli/
│ ├── index.ts # CLI entry point
│ └── commands.ts # CLI commands
└── lib/
├── utils.ts # Utility functions
├── logger.ts # Logging configuration
└── config.ts # Configuration management
tests/
├── unit/
│ ├── adapters/
│ ├── protocol/
│ ├── tools/
│ ├── security/
│ └── metrics/
├── integration/
│ ├── e2e-debugging.test.ts
│ ├── multi-language.test.ts
│ ├── transport.test.ts
│ └── event-polling.test.ts
└── fixtures/
├── sample-projects/
│ ├── node-app/
│ ├── python-app/
│ ├── csharp-app/
│ └── dart-app
└── mock-adapters/
adapters/
├── csharp/
│ ├── vsdbg/
│ ├── netcoredbg/
│ └── package.json
├── node/
│ ├── vscode-js-debug/
│ └── package.json
├── python/
│ ├── debugpy/
│ └── package.json
└── dart/
├── dart-debug-adapter/
├── flutter-dap/
└── package.json
docs/
├── quickstart.md # User quick start guide
├── api-reference.md # MCP API documentation
├── troubleshooting.md # Common issues and solutions
├── adapters.md # Adapter-specific configuration
└── samples/ # Usage examples
package.json
tsconfig.json
vitest.config.ts
esbuild.config.js
.gitignore
README.md
```
**Structure Decision**: Single project architecture with modular adapter system. Core MCP server and tools in `src/`, language-specific adapters in `src/adapters/`, integration tests for cross-language scenarios, and comprehensive sample projects in `tests/fixtures/`.
## Rollout Strategy
### Alpha (MVP)
- **Focus**: Node.js + Python launch debugging, stdio transport, basic event polling
- **Tools**: dap.start, dap.setBreakpoints, dap.continue, dap.pause, dap.step, dap.threads, dap.stackTrace, dap.scopes, dap.variables, dap.evaluate, dap.events.poll, dap.terminate
- **Metrics**: Basic logging and performance tracking
- **Testing**: Unit tests + manual Node.js/Python debugging
### Beta
- **Focus**: C# attach debugging + Dart support, enhanced metrics, diagnostic tool
- **Additions**: TCP transport, adapter validation, OpenTelemetry metrics
- **Testing**: Integration tests for all 4 languages, attach scenarios
- **Docs**: Troubleshooting guide, adapter configuration docs
### GA (General Availability)
- **Focus**: Documentation, sample projects, Windows CI, adapter pinning
- **Additions**: Comprehensive docs, sample projects, automated testing
- **Quality**: Performance validation, security audit, user feedback incorporation
## Complexity Tracking
*Constitution compliance maintained without complexity violations*
| Component | Complexity Justification | Alignment |
|-----------|--------------------------|-----------|
| Multi-adapter system | Required for 4 target language support; modular design allows independent adapter development and testing | Supports DAP as single source of truth principle |
| Event polling system | Required for agent compatibility; ring buffer design prevents memory issues while maintaining deterministic behavior | Aligns with deterministic debug loop principle |
| Transport abstraction | Necessary for stdio default + TCP attach; minimal surface area maintains principle compliance | Supports stdio-first transport principle |
| Security redaction | Critical for debugging scenarios; focused approach minimizes FS access while enabling debugging | Meets security-by-default requirements |