1# Research: Project Initialization Dependencies
2
3**Date**: 2025-01-09  
4**Context**: Resolve technical unknowns for dumber project initialization
5
6## Research Questions Resolved
7
8### 1. Go Module Initialization
9**Decision**: Use `go mod init dumber`
10**Rationale**: 
11- Simple module name matching the binary name
12- Local development focus (no public import path needed)
13- Follows Go module naming conventions
14
15**Alternatives considered**: 
16- `github.com/user/dumber` - rejected (unnecessary complexity for local tool)
17- `dumber/v1` - rejected (premature versioning)
18
19### 2. Wails v3-Alpha Compatibility
20**Decision**: Use Wails v3.0.0-alpha.28 (latest available)
21**Rationale**:
22- Constitution specifically requires v3-alpha
23- Alpha version provides newest WebKit2GTK integration
24- Active development branch with Wayland improvements
25- Breaking changes acceptable for new project
26
27**Alternatives considered**:
28- Wails v2 stable - rejected (constitution mandates v3-alpha)
29- Wait for v3 stable - rejected (delays development unnecessarily)
30
31**Integration approach**:
32```bash
33go install github.com/wailsapp/wails/v3/cmd/wails@v3.0.0-alpha.28
34```
35
36### 3. CLI Framework Selection
37**Decision**: Cobra v1.8+ with Viper v1.18+
38**Rationale**:
39- Constitution requirement: "Cobra + Viper for configuration"
40- Mature, stable libraries with excellent Go ecosystem integration
41- Perfect for dmenu/rofi integration via stdin/stdout
42- Built-in flag parsing and configuration management
43
44**Key packages**:
45- `github.com/spf13/cobra@latest`
46- `github.com/spf13/viper@latest`
47
48### 4. Database Stack
49**Decision**: SQLite with ncruces/go-sqlite3 (CGO-free) + SQLC v1.25+
50**Rationale**:
51- Constitution requirement: "SQLite + SQLC for type-safe SQL"
52- `github.com/ncruces/go-sqlite3` is CGO-free (better performance, fewer build issues)
53- Only Wails needs CGO, not database layer - cleaner separation
54- SQLC generates type-safe Go code from SQL schemas
55- Perfect for local history storage
56
57**Key packages**:
58- `github.com/ncruces/go-sqlite3@latest` (CGO-free SQLite driver)
59- Install SQLC CLI tool: `go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest`
60
61**Alternatives considered**:
62- `github.com/mattn/go-sqlite3` - rejected (requires CGO unnecessarily)
63- Pure Go implementations - rejected (ncruces is the modern standard)
64
65### 5. Input Validation
66**Decision**: go-playground/validator v10.16+
67**Rationale**:
68- Constitution requirement
69- Industry standard for Go struct validation
70- URL validation capabilities for browser input
71- Tag-based validation (clean code)
72
73**Key package**:
74- `github.com/go-playground/validator/v10@latest`
75
76### 6. Testing Framework
77**Decision**: Standard Go testing + testify v1.8+
78**Rationale**:
79- Standard library first approach (constitution: simplicity)
80- testify for better assertions and test organization
81- No need for heavyweight testing frameworks
82
83**Key package**:
84- `github.com/stretchr/testify@latest`
85
86### 7. Project Directory Structure
87**Decision**: Follow constitution implementation order
88```
89/
90├── cmd/                 # CLI entry point
91├── internal/
92│   ├── cli/            # Cobra commands
93│   ├── db/             # SQLC generated code + migrations
94│   ├── parser/         # URL parsing logic
95│   └── browser/        # Wails integration
96├── migrations/         # SQL schema files
97├── configs/           # Configuration files (SQLC, Wails)
98└── tests/             # Integration tests
99```
100
101**Rationale**:
102- `internal/` prevents external imports (Go convention)
103- Matches constitution implementation order
104- Separates concerns clearly
105- Easy to test individual components
106
107### 8. Build Configuration
108**Decision**: Standard Go build with Wails embedding
109**Rationale**:
110- Single binary requirement from constitution
111- Wails handles frontend asset embedding
112- Standard go build for CLI-only functionality
113
114## Dependency Installation Order
115
116Based on research, the installation sequence should be:
117
1181. **Initialize Go module**
119   ```bash
120   go mod init dumber
121   ```
122
1232. **Install CLI dependencies**
124   ```bash
125   go get github.com/spf13/cobra@latest
126   go get github.com/spf13/viper@latest
127   ```
128
1293. **Install database dependencies**
130   ```bash
131   go get github.com/ncruces/go-sqlite3@latest
132   go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest
133   ```
134
1354. **Install validation**
136   ```bash
137   go get github.com/go-playground/validator/v10@latest
138   ```
139
1405. **Install testing tools**
141   ```bash
142   go get github.com/stretchr/testify@latest
143   ```
144
1456. **Install Wails (last - most complex)**
146   ```bash
147   go install github.com/wailsapp/wails/v3/cmd/wails@v3.0.0-alpha.28
148   # Wails will handle its own module dependencies during init
149   ```
150
151## Risk Assessment
152
153**Low Risk**:
154- Standard Go dependencies (Cobra, Viper, SQLite)
155- Well-established patterns
156
157**Medium Risk**:
158- Wails v3-alpha stability (alpha software)
159- WebKit2GTK system dependency availability
160- CGO requirement for Wails (but not for database layer)
161
162**Mitigation**:
163- Test Wails installation immediately after dependency setup
164- Verify WebKit2GTK availability in integration tests
165- Document CGO requirement clearly (only for final Wails build)
166- Database layer can be developed/tested CGO-free independently
167
168## Next Phase Requirements
169
170All technical unknowns resolved. Phase 1 can proceed with:
171- Data model design (SQLite schema)
172- Contract definitions (CLI commands)
173- Integration test scenarios
174- Configuration file generation
175
176**Status**: ✅ Complete - All NEEDS CLARIFICATION items resolved