quickstart.md Raw History Folder

Quickstart: Project Initialization

Goal: Validate that project initialization works correctly and all dependencies are properly installed.

Prerequisites Verification

Before running quickstart, verify system requirements:

# Check Go version (1.25+ required)
go version
# Expected: go version go1.25.x linux/amd64

# Check system packages for Wails (Arch Linux)
pacman -Q webkit2gtk gtk3
# Expected: webkit2gtk-4.0 and gtk3 packages listed

# For Ubuntu/Debian:
# dpkg -l | grep -E "(webkit2gtk|libgtk-3)"

# Note: CGO only needed for Wails, not for database layer

Step 1: Project Initialization

Navigate to project root and initialize:

cd /home/brice/dev/projects/dumber

# Initialize with verbose output to see progress
dumber init --verbose

Expected Output:

✓ Initializing Go module: dumber
✓ Installing CLI dependencies: cobra, viper
✓ Installing database dependencies: ncruces/go-sqlite3, sqlc
✓ Installing validation: go-playground/validator
✓ Installing testing: testify
✓ Installing Wails v3-alpha... (requires CGO)
✓ Creating project structure...
✓ Generating configuration files...
✓ Verifying installation...

Project initialized successfully!

Next steps:
  1. Review generated configs/
  2. Run: go build ./cmd/dumber
  3. Start development: dumber --help

Step 2: Verify Installation

Check that all components are correctly installed:

# Verify project status
dumber init status

# Expected output:
# Project Status: ✓ Initialized
# Dependencies: ✓ All installed
# Structure: ✓ Complete
# Build Status: ✓ Ready

Detailed verification:

# Check go.mod exists and is valid
test -f go.mod && echo "✓ go.mod exists"
grep -q "module dumber" go.mod && echo "✓ Module name correct"

# Verify dependencies are downloadable
go mod download && echo "✓ Dependencies resolved"

# Check tools are available
sqlc version && echo "✓ SQLC available"
wails version && echo "✓ Wails available"

Step 3: Test CGO-Free Components

Most components can be tested without CGO enabled:

# Test CGO-free database layer
export CGO_ENABLED=0
go build ./internal/db && echo "✓ Database layer builds CGO-free"
go test ./internal/db && echo "✓ Database tests pass CGO-free"

# Test CLI components
go build ./internal/cli && echo "✓ CLI builds CGO-free" 
go test ./internal/cli && echo "✓ CLI tests pass CGO-free"

# Test URL parser
go build ./internal/parser && echo "✓ Parser builds CGO-free"
go test ./internal/parser && echo "✓ Parser tests pass CGO-free"

Step 4: Test Wails Integration (CGO Required)

Test the full application with Wails:

# Enable CGO for Wails
export CGO_ENABLED=1

# Test full application build
go build ./cmd/dumber && echo "✓ Full build successful"

# Clean up test binary
rm -f dumber

Step 5: Test Project Structure

Verify the correct directory structure was created:

# Check main directories exist
test -d cmd && echo "✓ cmd/ directory"
test -d internal && echo "✓ internal/ directory" 
test -d migrations && echo "✓ migrations/ directory"
test -d configs && echo "✓ configs/ directory"
test -d tests && echo "✓ tests/ directory"

# Check internal structure
test -d internal/cli && echo "✓ internal/cli/"
test -d internal/db && echo "✓ internal/db/"
test -d internal/parser && echo "✓ internal/parser/"
test -d internal/browser && echo "✓ internal/browser/"

Step 6: Test Configuration Generation

Verify that configuration files were generated correctly:

# Check SQLC configuration
test -f configs/sqlc.yaml && echo "✓ SQLC config exists"
sqlc compile -f configs/sqlc.yaml && echo "✓ SQLC config valid"

# Check basic project files exist (if generated)
test -f cmd/dumber/main.go && echo "✓ Main entry point exists"

Step 7: Test Module Dependencies

Verify the updated SQLite dependency:

# Check ncruces/go-sqlite3 is in go.mod (not mattn)
grep -q "github.com/ncruces/go-sqlite3" go.mod && echo "✓ Using CGO-free SQLite driver"
! grep -q "github.com/mattn/go-sqlite3" go.mod && echo "✓ Not using CGO SQLite driver"

# Test that database works CGO-free
export CGO_ENABLED=0
go run -c "import _ 'github.com/ncruces/go-sqlite3'" 2>/dev/null && echo "✓ SQLite driver loads CGO-free"

Step 8: Validation Tests

Run tests with different CGO settings:

# Test CGO-free components
export CGO_ENABLED=0
go test ./internal/cli ./internal/parser ./internal/db && echo "✓ CGO-free tests pass"

# Test full application with CGO
export CGO_ENABLED=1  
go test ./... && echo "✓ All tests pass with CGO"

# Test with race detection (requires CGO)
go test -race ./... && echo "✓ No race conditions detected"

Troubleshooting Common Issues

Issue: Missing WebKit2GTK (Wails only)

Symptom: Wails installation fails with webkit error Solution (Arch Linux):

sudo pacman -S webkit2gtk gtk3
dumber init deps --only=wails

Issue: CGO disabled for Wails

Symptom: Wails build fails with CGO error
Solution:

export CGO_ENABLED=1
go build ./cmd/dumber

Issue: Wrong SQLite driver

Symptom: CGO errors from mattn/go-sqlite3 Verification:

# Should show ncruces, not mattn
grep sqlite3 go.mod

Issue: Network timeout

Symptom: Dependency download timeouts Solution:

go env -w GOPROXY=proxy.golang.org,direct
go env -w GOSUMDB=sum.golang.org
dumber init deps

Success Criteria

After completing all steps, you should have:

✅ Valid Go module with CGO-free SQLite driver (ncruces/go-sqlite3)
✅ All CLI, parser, database components buildable with CGO_ENABLED=0
✅ Full application buildable with CGO_ENABLED=1 (for Wails)
✅ Project directory structure created per constitution
✅ Configuration files generated and valid
✅ All tools (sqlc, wails) available and functional
✅ Clean separation: CGO only needed for browser layer

Development Workflow Benefits

This CGO strategy provides several advantages:

Fast development cycle: Most development can happen CGO-free
Better testing: Database and CLI logic testable without CGO setup
Cleaner builds: Only final integration requires CGO
Better performance: ncruces/go-sqlite3 is faster than mattn/go-sqlite3

Next Steps

After successful initialization:

Start with CGO-free components: CLI structure, URL parsing, database schema
Test incrementally: Each component works independently
Integrate with Wails last: Final step requires CGO for browser integration
Development workflow: Most work can be done with CGO_ENABLED=0

The project is now ready for feature development with optimal CGO separation.

source

1# Quickstart: Project Initialization
2
3**Goal**: Validate that project initialization works correctly and all dependencies are properly installed.
4
5## Prerequisites Verification
6
7Before running quickstart, verify system requirements:
8
9```bash
10# Check Go version (1.25+ required)
11go version
12# Expected: go version go1.25.x linux/amd64
13
14# Check system packages for Wails (Arch Linux)
15pacman -Q webkit2gtk gtk3
16# Expected: webkit2gtk-4.0 and gtk3 packages listed
17
18# For Ubuntu/Debian:
19# dpkg -l | grep -E "(webkit2gtk|libgtk-3)"
20
21# Note: CGO only needed for Wails, not for database layer
22```
23
24## Step 1: Project Initialization
25
26Navigate to project root and initialize:
27
28```bash
29cd /home/brice/dev/projects/dumber
30
31# Initialize with verbose output to see progress
32dumber init --verbose
33```
34
35**Expected Output**:
36```
37✓ Initializing Go module: dumber
38✓ Installing CLI dependencies: cobra, viper
39✓ Installing database dependencies: ncruces/go-sqlite3, sqlc
40✓ Installing validation: go-playground/validator
41✓ Installing testing: testify
42✓ Installing Wails v3-alpha... (requires CGO)
43✓ Creating project structure...
44✓ Generating configuration files...
45✓ Verifying installation...
46
47Project initialized successfully!
48
49Next steps:
50  1. Review generated configs/
51  2. Run: go build ./cmd/dumber
52  3. Start development: dumber --help
53```
54
55## Step 2: Verify Installation
56
57Check that all components are correctly installed:
58
59```bash
60# Verify project status
61dumber init status
62
63# Expected output:
64# Project Status: ✓ Initialized
65# Dependencies: ✓ All installed
66# Structure: ✓ Complete
67# Build Status: ✓ Ready
68```
69
70Detailed verification:
71
72```bash
73# Check go.mod exists and is valid
74test -f go.mod && echo "✓ go.mod exists"
75grep -q "module dumber" go.mod && echo "✓ Module name correct"
76
77# Verify dependencies are downloadable
78go mod download && echo "✓ Dependencies resolved"
79
80# Check tools are available
81sqlc version && echo "✓ SQLC available"
82wails version && echo "✓ Wails available"
83```
84
85## Step 3: Test CGO-Free Components
86
87Most components can be tested without CGO enabled:
88
89```bash
90# Test CGO-free database layer
91export CGO_ENABLED=0
92go build ./internal/db && echo "✓ Database layer builds CGO-free"
93go test ./internal/db && echo "✓ Database tests pass CGO-free"
94
95# Test CLI components
96go build ./internal/cli && echo "✓ CLI builds CGO-free" 
97go test ./internal/cli && echo "✓ CLI tests pass CGO-free"
98
99# Test URL parser
100go build ./internal/parser && echo "✓ Parser builds CGO-free"
101go test ./internal/parser && echo "✓ Parser tests pass CGO-free"
102```
103
104## Step 4: Test Wails Integration (CGO Required)
105
106Test the full application with Wails:
107
108```bash
109# Enable CGO for Wails
110export CGO_ENABLED=1
111
112# Test full application build
113go build ./cmd/dumber && echo "✓ Full build successful"
114
115# Clean up test binary
116rm -f dumber
117```
118
119## Step 5: Test Project Structure
120
121Verify the correct directory structure was created:
122
123```bash
124# Check main directories exist
125test -d cmd && echo "✓ cmd/ directory"
126test -d internal && echo "✓ internal/ directory" 
127test -d migrations && echo "✓ migrations/ directory"
128test -d configs && echo "✓ configs/ directory"
129test -d tests && echo "✓ tests/ directory"
130
131# Check internal structure
132test -d internal/cli && echo "✓ internal/cli/"
133test -d internal/db && echo "✓ internal/db/"
134test -d internal/parser && echo "✓ internal/parser/"
135test -d internal/browser && echo "✓ internal/browser/"
136```
137
138## Step 6: Test Configuration Generation
139
140Verify that configuration files were generated correctly:
141
142```bash
143# Check SQLC configuration
144test -f configs/sqlc.yaml && echo "✓ SQLC config exists"
145sqlc compile -f configs/sqlc.yaml && echo "✓ SQLC config valid"
146
147# Check basic project files exist (if generated)
148test -f cmd/dumber/main.go && echo "✓ Main entry point exists"
149```
150
151## Step 7: Test Module Dependencies
152
153Verify the updated SQLite dependency:
154
155```bash
156# Check ncruces/go-sqlite3 is in go.mod (not mattn)
157grep -q "github.com/ncruces/go-sqlite3" go.mod && echo "✓ Using CGO-free SQLite driver"
158! grep -q "github.com/mattn/go-sqlite3" go.mod && echo "✓ Not using CGO SQLite driver"
159
160# Test that database works CGO-free
161export CGO_ENABLED=0
162go run -c "import _ 'github.com/ncruces/go-sqlite3'" 2>/dev/null && echo "✓ SQLite driver loads CGO-free"
163```
164
165## Step 8: Validation Tests
166
167Run tests with different CGO settings:
168
169```bash
170# Test CGO-free components
171export CGO_ENABLED=0
172go test ./internal/cli ./internal/parser ./internal/db && echo "✓ CGO-free tests pass"
173
174# Test full application with CGO
175export CGO_ENABLED=1  
176go test ./... && echo "✓ All tests pass with CGO"
177
178# Test with race detection (requires CGO)
179go test -race ./... && echo "✓ No race conditions detected"
180```
181
182## Troubleshooting Common Issues
183
184### Issue: Missing WebKit2GTK (Wails only)
185**Symptom**: Wails installation fails with webkit error
186**Solution** (Arch Linux):
187```bash
188sudo pacman -S webkit2gtk gtk3
189dumber init deps --only=wails
190```
191
192### Issue: CGO disabled for Wails
193**Symptom**: Wails build fails with CGO error  
194**Solution**:
195```bash
196export CGO_ENABLED=1
197go build ./cmd/dumber
198```
199
200### Issue: Wrong SQLite driver
201**Symptom**: CGO errors from mattn/go-sqlite3
202**Verification**:
203```bash
204# Should show ncruces, not mattn
205grep sqlite3 go.mod
206```
207
208### Issue: Network timeout
209**Symptom**: Dependency download timeouts
210**Solution**:
211```bash
212go env -w GOPROXY=proxy.golang.org,direct
213go env -w GOSUMDB=sum.golang.org
214dumber init deps
215```
216
217## Success Criteria
218
219After completing all steps, you should have:
220
221- ✅ Valid Go module with CGO-free SQLite driver (`ncruces/go-sqlite3`)
222- ✅ All CLI, parser, database components buildable with `CGO_ENABLED=0`
223- ✅ Full application buildable with `CGO_ENABLED=1` (for Wails)
224- ✅ Project directory structure created per constitution
225- ✅ Configuration files generated and valid
226- ✅ All tools (sqlc, wails) available and functional
227- ✅ Clean separation: CGO only needed for browser layer
228
229## Development Workflow Benefits
230
231This CGO strategy provides several advantages:
232
2331. **Fast development cycle**: Most development can happen CGO-free
2342. **Better testing**: Database and CLI logic testable without CGO setup
2353. **Cleaner builds**: Only final integration requires CGO
2364. **Better performance**: `ncruces/go-sqlite3` is faster than `mattn/go-sqlite3`
237
238## Next Steps
239
240After successful initialization:
241
2421. **Start with CGO-free components**: CLI structure, URL parsing, database schema
2432. **Test incrementally**: Each component works independently
2443. **Integrate with Wails last**: Final step requires CGO for browser integration
2454. **Development workflow**: Most work can be done with `CGO_ENABLED=0`
246
247The project is now ready for feature development with optimal CGO separation.

quickstart.md RawHistoryFolder