# Go Module Contract: Project Dependencies

# Expected go.mod file structure after initialization
module: dumb-browser
go_version: "1.25"

# Runtime dependencies (will be installed via go get @latest)
dependencies:
  cli:
    - import_path: "github.com/spf13/cobra"
      purpose: "CLI framework and command handling"
      min_version: "v1.8.0"
      
    - import_path: "github.com/spf13/viper"
      purpose: "Configuration management"
      min_version: "v1.18.0"

  database:
    - import_path: "github.com/ncruces/go-sqlite3"
      purpose: "CGO-free SQLite database driver"
      min_version: "v0.28.0"
      build_tags: []
      requirements: []
      benefits: ["no CGO required", "better performance", "cleaner builds"]

  validation:
    - import_path: "github.com/go-playground/validator/v10"
      purpose: "Struct validation and input sanitization"
      min_version: "v10.16.0"

  testing:
    - import_path: "github.com/stretchr/testify"
      purpose: "Enhanced testing assertions and mocks"
      min_version: "v1.8.4"
      scope: "test"

# Development tools (installed via go install)
tools:
  - name: "sqlc"
    install_command: "go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest"
    purpose: "Generate type-safe Go code from SQL"
    version_check: "sqlc version"
    
  - name: "wails"
    install_command: "go install github.com/wailsapp/wails/v3/cmd/wails@v3.0.0-alpha.28"
    purpose: "Desktop application framework"
    version_check: "wails version"
    system_deps: ["libwebkit2gtk-4.0-dev", "libgtk-3-dev"]

# Expected go.mod content template
go_mod_template: |
  module dumb-browser
  
  go 1.21
  
  require (
      github.com/spf13/cobra v1.8.0
      github.com/spf13/viper v1.18.2
      github.com/ncruces/go-sqlite3 v0.28.0
      github.com/go-playground/validator/v10 v10.16.0
      github.com/stretchr/testify v1.8.4
  )

# Compatibility matrix
compatibility:
  go_version:
    minimum: "1.18"  # Required for generics
    recommended: "1.21"
    maximum: "1.22"
    
  operating_systems:
    primary: "linux"
    supported: ["linux", "darwin"]
    tested: ["archlinux", "ubuntu-22.04"]
    
  architectures:
    primary: "amd64"
    supported: ["amd64", "arm64"]

# Build configuration
build:
  tags:
    development: ["dev", "debug"]
    production: []
    testing: ["test", "integration"]
    
  environment:
    wails_build:
      - name: "CGO_ENABLED"
        value: "1"  
        reason: "Required for Wails WebKit2GTK bindings"
    cgo_free_development:
      - name: "CGO_ENABLED"
        value: "0"
        reason: "Most development can happen CGO-free (CLI, database, parser)"
        
  flags:
    development: "-race -v"
    production: "-ldflags='-s -w'"
    
# Verification commands
verification:
  module_valid: "go mod verify"
  dependencies_resolved: "go mod download"
  build_succeeds: "go build ./cmd/dumb-browser"
  tests_pass: "go test ./..."
  tools_available: 
    - "sqlc version"
    - "wails version"

# Installation success criteria
success_criteria:
  - name: "go.mod exists"
    command: "test -f go.mod"
    
  - name: "module name correct"
    command: "grep -q 'module dumb-browser' go.mod"
    
  - name: "all dependencies resolved"
    command: "go mod download && echo 'OK'"
    
  - name: "build succeeds"
    command: "go build -o /tmp/test-build ./cmd/dumb-browser"
    cleanup: "rm -f /tmp/test-build"
    
  - name: "sqlc available"
    command: "which sqlc && sqlc version"
    
  - name: "wails available" 
    command: "which wails && wails version"
    
# Error conditions and solutions
error_handling:
  cgo_disabled_for_wails:
    error_pattern: "C compiler|CGO_ENABLED.*wails"
    solution: "export CGO_ENABLED=1 # Only needed for Wails builds"
    documentation: "Wails requires CGO for WebKit2GTK bindings (database layer is CGO-free)"
    
  missing_webkit:
    error_pattern: "webkit2gtk|libwebkit2gtk"
    solution: "sudo apt install libwebkit2gtk-4.0-dev libgtk-3-dev"
    documentation: "Wails requires WebKit2GTK development headers"
    
  network_failure:
    error_pattern: "dial tcp|connection refused|timeout"
    solution: "Check internet connection and proxy settings"
    documentation: "Dependency installation requires network access"
    
  insufficient_space:
    error_pattern: "no space left|disk full"
    solution: "Free up disk space and try again"
    documentation: "Go module cache and tools require ~500MB space"