go-module.yaml RawHistoryFolder

1# Go Module Contract: Project Dependencies
2
3# Expected go.mod file structure after initialization
4module: dumb-browser
5go_version: "1.25"
6
7# Runtime dependencies (will be installed via go get @latest)
8dependencies:
9  cli:
10    - import_path: "github.com/spf13/cobra"
11      purpose: "CLI framework and command handling"
12      min_version: "v1.8.0"
13      
14    - import_path: "github.com/spf13/viper"
15      purpose: "Configuration management"
16      min_version: "v1.18.0"
17
18  database:
19    - import_path: "github.com/ncruces/go-sqlite3"
20      purpose: "CGO-free SQLite database driver"
21      min_version: "v0.28.0"
22      build_tags: []
23      requirements: []
24      benefits: ["no CGO required", "better performance", "cleaner builds"]
25
26  validation:
27    - import_path: "github.com/go-playground/validator/v10"
28      purpose: "Struct validation and input sanitization"
29      min_version: "v10.16.0"
30
31  testing:
32    - import_path: "github.com/stretchr/testify"
33      purpose: "Enhanced testing assertions and mocks"
34      min_version: "v1.8.4"
35      scope: "test"
36
37# Development tools (installed via go install)
38tools:
39  - name: "sqlc"
40    install_command: "go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest"
41    purpose: "Generate type-safe Go code from SQL"
42    version_check: "sqlc version"
43    
44  - name: "wails"
45    install_command: "go install github.com/wailsapp/wails/v3/cmd/wails@v3.0.0-alpha.28"
46    purpose: "Desktop application framework"
47    version_check: "wails version"
48    system_deps: ["libwebkit2gtk-4.0-dev", "libgtk-3-dev"]
49
50# Expected go.mod content template
51go_mod_template: |
52  module dumb-browser
53  
54  go 1.21
55  
56  require (
57      github.com/spf13/cobra v1.8.0
58      github.com/spf13/viper v1.18.2
59      github.com/ncruces/go-sqlite3 v0.28.0
60      github.com/go-playground/validator/v10 v10.16.0
61      github.com/stretchr/testify v1.8.4
62  )
63
64# Compatibility matrix
65compatibility:
66  go_version:
67    minimum: "1.18"  # Required for generics
68    recommended: "1.21"
69    maximum: "1.22"
70    
71  operating_systems:
72    primary: "linux"
73    supported: ["linux", "darwin"]
74    tested: ["archlinux", "ubuntu-22.04"]
75    
76  architectures:
77    primary: "amd64"
78    supported: ["amd64", "arm64"]
79
80# Build configuration
81build:
82  tags:
83    development: ["dev", "debug"]
84    production: []
85    testing: ["test", "integration"]
86    
87  environment:
88    wails_build:
89      - name: "CGO_ENABLED"
90        value: "1"  
91        reason: "Required for Wails WebKit2GTK bindings"
92    cgo_free_development:
93      - name: "CGO_ENABLED"
94        value: "0"
95        reason: "Most development can happen CGO-free (CLI, database, parser)"
96        
97  flags:
98    development: "-race -v"
99    production: "-ldflags='-s -w'"
100    
101# Verification commands
102verification:
103  module_valid: "go mod verify"
104  dependencies_resolved: "go mod download"
105  build_succeeds: "go build ./cmd/dumb-browser"
106  tests_pass: "go test ./..."
107  tools_available: 
108    - "sqlc version"
109    - "wails version"
110
111# Installation success criteria
112success_criteria:
113  - name: "go.mod exists"
114    command: "test -f go.mod"
115    
116  - name: "module name correct"
117    command: "grep -q 'module dumb-browser' go.mod"
118    
119  - name: "all dependencies resolved"
120    command: "go mod download && echo 'OK'"
121    
122  - name: "build succeeds"
123    command: "go build -o /tmp/test-build ./cmd/dumb-browser"
124    cleanup: "rm -f /tmp/test-build"
125    
126  - name: "sqlc available"
127    command: "which sqlc && sqlc version"
128    
129  - name: "wails available" 
130    command: "which wails && wails version"
131    
132# Error conditions and solutions
133error_handling:
134  cgo_disabled_for_wails:
135    error_pattern: "C compiler|CGO_ENABLED.*wails"
136    solution: "export CGO_ENABLED=1 # Only needed for Wails builds"
137    documentation: "Wails requires CGO for WebKit2GTK bindings (database layer is CGO-free)"
138    
139  missing_webkit:
140    error_pattern: "webkit2gtk|libwebkit2gtk"
141    solution: "sudo apt install libwebkit2gtk-4.0-dev libgtk-3-dev"
142    documentation: "Wails requires WebKit2GTK development headers"
143    
144  network_failure:
145    error_pattern: "dial tcp|connection refused|timeout"
146    solution: "Check internet connection and proxy settings"
147    documentation: "Dependency installation requires network access"
148    
149  insufficient_space:
150    error_pattern: "no space left|disk full"
151    solution: "Free up disk space and try again"
152    documentation: "Go module cache and tools require ~500MB space"