Watchtower DAP Windows Debugging

--- description: "Task list template for feature implementation" --- # Tasks: Watchtower DAP Windows Debugging **Input**: Design documents from `/specs/001-dap-windows-debug/` **Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/ **Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification. **Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story. ## Format: `[ID] [P?] [Story] Description` - **[P]**: Can run in parallel (different files, no dependencies) - **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3) - Include exact file paths in descriptions ## Path Conventions - **Single project**: `src/`, `tests/` at repository root - **Web app**: `backend/src/`, `frontend/src/` - **Mobile**: `api/src/`, `ios/src/` or `android/src/` - Paths shown below assume single project - adjust based on plan.md structure ## Phase 1: Setup (Shared Infrastructure) **Purpose**: Project initialization and basic structure - [ ] T001 Bootstrap repo: engines (Node 22), tsconfig, eslint/prettier, vitest config - [ ] T002 [P] Install deps: @modelcontextprotocol/sdk, vscode-jsonrpc, @vscode/debugprotocol, zod, execa, commander, pino, opentelemetry-sdk-node, esbuild; dev: typescript, vitest, @types/node - [ ] T003 Scaffold MCP server (name: watchtower); CLI 'watchtower serve' (commander) --- ## Phase 2: Foundational (Blocking Prerequisites) **Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented **⚠️ CRITICAL**: No user story work can begin until this phase is complete - [ ] T004 Define Zod schemas for tools: dap.start/setBreakpoints/continue/pause/step/threads/stackTrace/scopes/variables/evaluate/events.poll/terminate/disconnect - [ ] T005 [P] Implement DAP stdio transport with vscode-jsonrpc (Content-Length framing) - [ ] T006 [P] Session manager: initialize → configurationDone → launch/attach; capability negotiation; error taxonomy - [ ] T007 [P] Adapter registry & locator (Windows): probe vsdbg, netcoredbg, js-debug, debugpy, dart; friendly install hints - [ ] T008 [P] Security: env/args redaction; rotating file sink (pino) - [ ] T009 [P] OpenTelemetry metrics: TFFB, STEP_p95, SR, BP1; OTLP exporter toggle - [ ] T010 [P] Per-session event ring buffer with cursor pagination; implement events.poll(since,limit) **Checkpoint**: Foundation ready - user story implementation can now begin in parallel --- ## Phase 3: User Story 1 - Cross-Language Debugging Setup (Priority: P1) 🎯 MVP **Goal**: Core Node.js debugging capability with breakpoints and stepping **Independent Test**: Can be fully tested by launching Node.js app, setting breakpoint, hitting it, and stepping through code execution ### Tests for User Story 1 (Alpha testing) **NOTE: Write these tests FIRST, ensure they FAIL before implementation** - [ ] T011 [P] [US1] Contract test for MCP server initialization in tests/contract/test_mcp-server.ts - [ ] T012 [P] [US1] Integration test for Node.js debugging flow in tests/integration/test-node-debugging.ts ### Implementation for User Story 1 - [ ] T013 [P] [US1] Node (js-debug): launch (program,cwd) and attach (9229); return breakpoint verification diagnostics - [ ] T014 [P] [US1] Execution controls: pause/continue/stepIn/stepOver/stepOut; terminate/disconnect with idempotency - [ ] T015 [US1] Implement dap.start tool in src/tools/start.ts - [ ] T016 [US1] Implement dap.setBreakpoints tool in src/tools/breakpoints.ts - [ ] T017 [US1] Implement dap.continue, dap.pause, dap.step tools in src/tools/stepping.ts - [ ] T018 [US1] Implement dap.threads tool in src/tools/threads.ts - [ ] T019 [US1] Implement dap.stackTrace, dap.scopes, dap.variables in src/tools/stack.ts - [ ] T020 [US1] Implement dap.evaluate tool in src/tools/evaluate.ts - [ ] T021 [US1] Integrate Node.js adapter with MCP server in src/server/session-manager.ts - [ ] T022 [US1] Add event polling support in src/tools/events.ts - [ ] T023 [US1] Implement dap.terminate and dap.disconnect tools in src/tools/session.ts **Checkpoint**: At this point, User Story 1 should be fully functional and testable independently --- ## Phase 4: User Story 2 - Multi-Language Project Debugging (Priority: P2) **Goal**: Support for all 4 target languages through unified MCP interface **Independent Test**: Can be tested by debugging Python service and Node.js API in separate sessions ### Tests for User Story 2 (Beta testing) - [ ] T024 [P] [US2] Contract test for Python adapter in tests/contract/test-python-adapter.ts - [ ] T025 [P] [US2] Integration test for C# attach debugging in tests/integration/test-csharp-debugging.ts - [ ] T026 [P] [US2] Cross-language debugging session tests in tests/integration/test-multi-lang.ts ### Implementation for User Story 2 - [ ] T027 [P] [US2] Python (debugpy): launch & attach (--listen/--wait-for-client); frame-scoped evaluate - [ ] T028 [P] [US2] C# (vsdbg): launch & attach (processId); netcoredbg fallback path - [ ] T029 [P] [US2] Dart/Flutter DAP: launch; attach via VM service URI; hot-reload-safe stepping - [ ] T030 [US2] Implement adapter factory and discovery system in src/adapters/index.ts - [ ] T031 [US2] Add language-specific breakpoint validation and mapping - [ ] T032 [US2] Enhance event polling for multi-language scenarios - [ ] T033 [US2] Implement adapter health checks and diagnostics - [ ] T034 [US2] Add support for source maps in TypeScript debugging **Checkpoint**: At this point, User Stories 1 AND 2 should both work independently --- ## Phase 5: User Story 3 - Remote Process Attachment (Priority: P3) **Goal**: Enable debugging of already running processes without restart **Independent Test**: Can be tested by launching separate process, then using MCP tools to attach and set breakpoints ### Tests for User Story 3 (Beta testing) - [ ] T035 [P] [US3] Contract test for process attachment in tests/contract/test-attach.ts - [ ] T036 [P] [US3] Integration test for remote debugging scenarios in tests/integration/test-remote-debug.ts ### Implementation for User Story 3 - [ ] T037 [P] [US3] Enhance transport to support TCP for attach scenarios - [ ] T038 [US3] Implement process discovery and attachment logic in src/transport/tcp.ts - [ ] T039 [US3] Add breakpoint validation for running processes - [ ] T040 [US3] Implement attach-specific error handling and diagnostics - [ ] T041 [US3] Update all language adapters to support attach mode **Checkpoint**: All user stories should now be independently functional --- ## Phase 6: Polish & Cross-Cutting Concerns **Purpose**: Improvements that affect multiple user stories - [ ] T042 [P] CLI 'watchtower doctor' to validate adapters, PATH, permissions, ports. CI-friendly exit codes - [ ] T043 [P] Bundle with esbuild; produce single JS artifact; optional single-file exe (pkg/nexe) later - [ ] T044 [P] Samples: minimal apps for C#/Node/Python/Dart with a known breakpoint line - [ ] T045 [P] Windows CI: run integration (init → launch → break → inspect → eval → step → terminate) per language - [ ] T046 [P] Documentation updates in docs/quickstart.md, docs/attach-recipes.md, docs/troubleshooting.md - [ ] T047 [P] Claude Code MCP config snippet in docs/ - [ ] T048 Security hardening and validation - [ ] T049 Performance optimization across all stories - [ ] T050 Code cleanup and refactoring --- ## Dependencies & Execution Order ### Phase Dependencies - **Setup (Phase 1)**: No dependencies - can start immediately - **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories - **User Stories (Phase 3+)**: All depend on Foundational phase completion - User stories can then proceed in parallel (if staffed) - Or sequentially in priority order (P1 → P2 → P3) - **Polish (Final Phase)**: Depends on all desired user stories being complete ### User Story Dependencies - **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories - **User Story 2 (P2)**: Can start after Foundational (Phase 2) - Depends on US1 architecture but extends to additional languages - **User Story 3 (P3)**: Can start after Foundational (Phase 2) - Enhances US1/US2 with attach capability ### Within Each User Story - Tests (if included) MUST be written and FAIL before implementation - Core adapter implementation before MCP tool integration - Base tools before advanced features - Story complete before moving to next priority ### Parallel Opportunities - All Setup tasks marked [P] can run in parallel - All Foundational tasks marked [P] can run in parallel (within Phase 2) - Once Foundational phase completes, all user stories can start in parallel (if team capacity allows) - All tests for a user story marked [P] can run in parallel - Adapter implementations marked [P] can run in parallel - Different user stories can be worked on in parallel by different team members --- ## Parallel Example: User Story 1 ```bash # Launch all tests for User Story 1 together: Task: "Contract test for MCP server initialization in tests/contract/test_mcp-server.ts" Task: "Integration test for Node.js debugging flow in tests/integration/test-node-debugging.ts" # Launch all core adapter tools together: Task: "Node (js-debug): launch (program,cwd) and attach (9229); return breakpoint verification diagnostics" Task: "Python (debugpy): launch & attach (--listen/--wait-for-client); frame-scoped evaluate" Task: "C# (vsdbg): launch & attach (processId); netcoredbg fallback path" ``` --- ## Implementation Strategy ### MVP First (User Story 1 Only) 1. Complete Phase 1: Setup 2. Complete Phase 2: Foundational (CRITICAL - blocks all stories) 3. Complete Phase 3: User Story 1 (Node.js debugging) 4. **STOP and VALIDATE**: Test Node.js debugging independently 5. Deploy to Alpha users for feedback ### Incremental Delivery 1. Complete Setup + Foundational → Foundation ready 2. Add User Story 1 → Test independently → Alpha Release (MVP!) 3. Add User Story 2 → Test independently → Beta Release 4. Add User Story 3 → Test independently → GA Release 5. Each story adds value without breaking previous stories ### Parallel Team Strategy With multiple developers: 1. Team completes Setup + Foundational together 2. Once Foundational is done: - Developer A: User Story 1 (Node.js core) - Developer B: User Story 2 (Python/C#/Dart adapters) - Developer C: User Story 3 (Attach capabilities) 3. Stories complete and integrate independently --- ## Notes - [P] tasks = different files, no dependencies - [Story] label maps task to specific user story for traceability - Each user story should be independently completable and testable - Verify tests fail before implementing - Commit after each task or logical group - Stop at any checkpoint to validate story independently - Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence