Skip to content

Commit e00c594

Browse files
masegrayemasegraye
committed
Spec refinements
1 parent e2ece15 commit e00c594

File tree

1 file changed

+250
-2
lines changed

1 file changed

+250
-2
lines changed

‎docs/feature-specs/catalog-management/implementation-checklist.md

Lines changed: 250 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,177 @@
66
**Feature Spec**: [feature-spec.md](./feature-spec.md)
77
**Investigation Notes**: `/Users/masegraye/dev/docker/id-writing/scratch/mcp-gateway-investigation.md`
88

9+
## Development Workflow & TDD Instructions
10+
11+
### Essential Commands for Development
12+
13+
All commands should be run from `/Users/masegraye/dev/docker/workspaces/catalog-management/mcp-gateway/`:
14+
15+
```bash
16+
# Scoped Test-Driven Development Cycle
17+
go test ./cmd/docker-mcp/commands # Test specific package (fastest)
18+
go test ./cmd/docker-mcp/... # Test cmd tree (medium scope)
19+
make test # Test entire system (broadest scope)
20+
make docker-mcp # Build and install binary (only after tests pass)
21+
make lint-darwin # Run linting (only when implementation complete)
22+
23+
# Manual testing commands
24+
./dist/docker-mcp --help # Verify binary works
25+
./dist/docker-mcp catalog --help # Check catalog commands
26+
./dist/docker-mcp gateway run --help # Check gateway flags
27+
```
28+
29+
### TDD Development Process
30+
31+
**CRITICAL**: Follow this exact workflow with progressively broader scope:
32+
33+
#### 1. Red Phase - Write Failing Tests First
34+
```bash
35+
# Test just the specific package you're working on
36+
go test ./cmd/docker-mcp/commands # Example: testing feature commands
37+
# Should show failing tests for new functionality
38+
```
39+
40+
#### 2. Green Phase - Make Tests Pass
41+
```bash
42+
# Write minimal implementation to make tests pass
43+
go test ./cmd/docker-mcp/commands # Test same package again
44+
# Should show all tests passing in that package
45+
```
46+
47+
#### 3. Package Integration Test
48+
```bash
49+
# Test all related packages together
50+
go test ./cmd/docker-mcp/... # Test entire cmd tree
51+
# Should show all tests passing across packages
52+
```
53+
54+
#### 4. Full System Test
55+
```bash
56+
# Test the entire system
57+
make test
58+
# Should show all tests passing system-wide
59+
```
60+
61+
#### 5. Build Phase - Verify Compilation
62+
```bash
63+
# Only build after all tests pass
64+
make docker-mcp
65+
# Should build successfully and install to ~/.docker/cli-plugins/docker-mcp
66+
```
67+
68+
#### 6. Manual Verification
69+
```bash
70+
# Test the actual CLI functionality
71+
./dist/docker-mcp [your-new-command] --help
72+
# Verify your changes work as expected
73+
```
74+
75+
#### 7. Refactor Phase (Optional)
76+
```bash
77+
# Improve code while keeping tests green
78+
go test ./path/to/package # Test specific package after changes
79+
```
80+
81+
#### 8. Lint Phase (End of Implementation Only)
82+
```bash
83+
# Only run linting when feature is complete
84+
make lint-darwin
85+
# Should show 0 issues
86+
```
87+
88+
### Test Categories & Strategy
89+
90+
#### Unit Tests (Primary Focus)
91+
- **Location**: Tests should be in `*_test.go` files alongside implementation
92+
- **Speed**: Fast (< 1 second per test file)
93+
- **Focus**: Individual function/method behavior
94+
- **Run Command**: `make test`
95+
96+
#### Integration Tests (Secondary)
97+
- **Location**: `cmd/docker-mcp/integration_test.go` and similar
98+
- **Speed**: Slower (requires Docker daemon)
99+
- **Focus**: End-to-end command workflows
100+
- **Note**: Some are skipped in normal `make test` runs
101+
102+
#### Manual Tests (Verification)
103+
- **Purpose**: Verify CLI behavior matches expectations
104+
- **When**: After successful build, before marking tasks complete
105+
- **Focus**: User experience and error messages
106+
107+
### Implementation Guidelines
108+
109+
1. **Test First**: Always write tests before implementation
110+
2. **Small Steps**: Implement one small piece at a time
111+
3. **Green Tests**: Never commit with failing tests
112+
4. **Build Validation**: Only build after tests pass
113+
5. **Manual Check**: Always verify CLI behavior manually
114+
6. **Lint Last**: Only run linting when implementation is complete
115+
116+
### Error Handling Strategy
117+
118+
#### Test Failures
119+
```bash
120+
make test
121+
# If tests fail, fix the code, don't skip tests
122+
```
123+
124+
#### Build Failures
125+
```bash
126+
make docker-mcp
127+
# If build fails, check compilation errors and fix
128+
# Don't proceed to manual testing until build succeeds
129+
```
130+
131+
#### Lint Failures (End of Development)
132+
```bash
133+
make lint-darwin
134+
# Fix all linting issues before marking feature complete
135+
```
136+
137+
### Baseline Verification ✅
138+
139+
The following baseline tests have been verified to work:
140+
- `make docker-mcp` - Builds successfully
141+
- `make test` - All existing tests pass
142+
- `make lint-darwin` - 0 linting issues
143+
- CLI functionality verified working
144+
145+
**Ready to begin TDD implementation following the above workflow.**
146+
147+
## 🧪 Test Strategy Overview
148+
149+
### Required Test Files for TDD Implementation
150+
151+
Each implementation section below specifies **TEST FIRST** requirements. These test files must be created with failing tests before writing implementation code:
152+
153+
| Component | Test File | Purpose |
154+
|-----------|-----------|---------|
155+
| Feature Management | `cmd/docker-mcp/commands/feature_test.go` | Test feature enable/disable/list commands |
156+
| Gateway Enhancement | `cmd/docker-mcp/commands/gateway_test.go` | Test --use-configured-catalogs flag validation |
157+
| Catalog Loading | `cmd/docker-mcp/internal/catalog/catalog_test.go` | Test catalog precedence and loading logic |
158+
| Export Command | `cmd/docker-mcp/catalog/export_test.go` | Test export functionality and protection |
159+
| Command Visibility | `cmd/docker-mcp/catalog/*_test.go` | Test unhidden commands appear in help |
160+
161+
### Test-First Workflow Reminder
162+
163+
```bash
164+
# 1. Write failing tests first
165+
go test ./cmd/docker-mcp/commands -v # Should show failing tests
166+
167+
# 2. Write minimal implementation
168+
go test ./cmd/docker-mcp/commands -v # Should show passing tests
169+
170+
# 3. Test broader scope
171+
go test ./cmd/docker-mcp/... -v # Should show all integration tests pass
172+
173+
# 4. Test full system
174+
make test # Should show all system tests pass
175+
176+
# 5. Build and verify
177+
make docker-mcp # Should build successfully
178+
```
179+
9180
## Quick Context for Claude Code Sessions
10181

11182
### What This Feature Does
@@ -26,11 +197,32 @@ Enable users to create and manage custom MCP server catalogs that automatically
26197
### Phase 1: Core Implementation
27198

28199
#### 1.1 Feature Management System
200+
201+
**🧪 TEST FIRST**: `cmd/docker-mcp/commands/feature_test.go`
202+
- [ ] **Write tests for feature command structure**
203+
```go
204+
// Test cases needed:
205+
func TestFeatureEnableCommand(t *testing.T) // Test enabling configured-catalogs
206+
func TestFeatureDisableCommand(t *testing.T) // Test disabling configured-catalogs
207+
func TestFeatureListCommand(t *testing.T) // Test listing all features and status
208+
func TestFeatureInvalidFeature(t *testing.T) // Test error for unknown feature names
209+
```
210+
29211
- [ ] **Create feature command structure**
30212
- [ ] File: `cmd/docker-mcp/commands/feature.go`
31213
- [ ] Commands: `enable <feature>`, `disable <feature>`, `list`
32214
- [ ] Target: `~/.docker/config.json` → `features.configured-catalogs`
33215

216+
**🧪 TEST FIRST**: `cmd/docker-mcp/commands/feature_test.go` (validation utilities)
217+
- [ ] **Write tests for feature validation utilities**
218+
```go
219+
// Test cases needed:
220+
func TestIsFeatureEnabledTrue(t *testing.T) // Test when feature is enabled
221+
func TestIsFeatureEnabledFalse(t *testing.T) // Test when feature is disabled
222+
func TestIsFeatureEnabledMissing(t *testing.T) // Test when config missing
223+
func TestIsFeatureEnabledCorrupt(t *testing.T) // Test when config corrupted
224+
```
225+
34226
- [ ] **Feature validation utilities**
35227
- [ ] Function: `isFeatureEnabled(dockerCli command.Cli, feature string) bool`
36228
- [ ] Handle missing config file gracefully
@@ -42,6 +234,16 @@ Enable users to create and manage custom MCP server catalogs that automatically
42234

43235
#### 1.2 Gateway Command Enhancement
44236

237+
**🧪 TEST FIRST**: `cmd/docker-mcp/commands/gateway_test.go`
238+
- [ ] **Write tests for gateway flag validation**
239+
```go
240+
// Test cases needed:
241+
func TestGatewayUseConfiguredCatalogsEnabled(t *testing.T) // Test flag works when feature enabled
242+
func TestGatewayUseConfiguredCatalogsDisabled(t *testing.T) // Test flag fails when feature disabled
243+
func TestGatewayFeatureFlagErrorMessage(t *testing.T) // Test error message clarity
244+
func TestGatewayContainerModeDetection(t *testing.T) // Test container mode handling
245+
```
246+
45247
- [ ] **Add --use-configured-catalogs flag**
46248
- [ ] File: `cmd/docker-mcp/commands/gateway.go`
47249
- [ ] Flag: `--use-configured-catalogs` (boolean)
@@ -58,8 +260,20 @@ Enable users to create and manage custom MCP server catalogs that automatically
58260

59261
#### 1.3 Catalog Loading Enhancement
60262

263+
**🧪 TEST FIRST**: `cmd/docker-mcp/internal/catalog/catalog_test.go`
264+
- [ ] **Write tests for catalog loading logic**
265+
```go
266+
// Test cases needed:
267+
func TestCatalogGetWithConfigured(t *testing.T) // Test loading configured catalogs
268+
func TestCatalogGetWithoutConfigured(t *testing.T) // Test default behavior unchanged
269+
func TestGetConfiguredCatalogsSuccess(t *testing.T) // Test reading catalog.json
270+
func TestGetConfiguredCatalogsMissing(t *testing.T) // Test missing catalog.json
271+
func TestGetConfiguredCatalogsCorrupt(t *testing.T) // Test corrupted catalog.json
272+
func TestCatalogPrecedenceOrder(t *testing.T) // Test Docker → Configured → CLI order
273+
```
274+
61275
- [ ] **Update catalog.Get() signature**
62-
- [ ] File: `cmd/docker-mcp/catalog/catalog.go`
276+
- [ ] File: `cmd/docker-mcp/internal/catalog/catalog.go`
63277
- [ ] New signature: `Get(ctx context.Context, useConfigured bool, additionalCatalogs []string) (Catalog, error)`
64278
- [ ] Backward compatibility: Keep current `Get()` for existing callers
65279

@@ -75,8 +289,18 @@ Enable users to create and manage custom MCP server catalogs that automatically
75289

76290
#### 1.4 Enhanced Conflict Resolution & Logging
77291

292+
**🧪 TEST FIRST**: `cmd/docker-mcp/internal/catalog/catalog_test.go` (conflict resolution)
293+
- [ ] **Write tests for conflict resolution**
294+
```go
295+
// Test cases needed:
296+
func TestReadFromConflictResolution(t *testing.T) // Test server name conflicts
297+
func TestReadFromLogging(t *testing.T) // Test logging output
298+
func TestReadFromSourceTracking(t *testing.T) // Test server source tracking
299+
func TestReadFromLastWinsPrecedence(t *testing.T) // Test "last wins" behavior
300+
```
301+
78302
- [ ] **Update ReadFrom() logging**
79-
- [ ] File: `cmd/docker-mcp/catalog/catalog.go`
303+
- [ ] File: `cmd/docker-mcp/internal/catalog/catalog.go`
80304
- [ ] Log catalog loading progress
81305
- [ ] Log server additions and conflicts
82306
- [ ] Log final catalog statistics
@@ -88,6 +312,18 @@ Enable users to create and manage custom MCP server catalogs that automatically
88312

89313
#### 1.5 Export Command Implementation
90314

315+
**🧪 TEST FIRST**: `cmd/docker-mcp/catalog/export_test.go`
316+
- [ ] **Write tests for export command**
317+
```go
318+
// Test cases needed:
319+
func TestExportCommandSuccess(t *testing.T) // Test successful export
320+
func TestExportCommandDefaultFilename(t *testing.T) // Test default filename generation
321+
func TestExportCommandCustomFilename(t *testing.T) // Test custom output file
322+
func TestExportCommandDockerCatalogBlocked(t *testing.T) // Test docker-mcp protection
323+
func TestExportCommandCatalogNotFound(t *testing.T) // Test missing catalog error
324+
func TestExportCommandPermissionError(t *testing.T) // Test file permission errors
325+
```
326+
91327
- [ ] **Create export command**
92328
- [ ] File: `cmd/docker-mcp/catalog/export.go` (new)
93329
- [ ] Command: `export <catalog-name> [output-file]`
@@ -106,6 +342,18 @@ Enable users to create and manage custom MCP server catalogs that automatically
106342
107343
#### 1.6 Command Visibility Updates
108344
345+
**🧪 TEST FIRST**: `cmd/docker-mcp/catalog/*_test.go` (existing command tests)
346+
- [ ] **Write tests for command visibility**
347+
```go
348+
// Test cases needed (add to existing test files):
349+
func TestImportCommandVisible(t *testing.T) // Test import command shows in help
350+
func TestExportCommandVisible(t *testing.T) // Test export command shows in help
351+
func TestCreateCommandVisible(t *testing.T) // Test create command shows in help
352+
func TestAddCommandVisible(t *testing.T) // Test add command shows in help
353+
func TestForkCommandVisible(t *testing.T) // Test fork command shows in help
354+
func TestRmCommandVisible(t *testing.T) // Test rm command shows in help
355+
```
356+
109357
- [ ] **Unhide catalog CRUD commands**
110358
- [ ] Files: `cmd/docker-mcp/catalog/{import,export,create,add,fork,rm}.go`
111359
- [ ] Remove `Hidden: true` from command definitions

0 commit comments

Comments
 (0)