@mytechtoday/augment-extensions 1.4.0 → 1.5.0

package/augment-extensions/coding-standards/go/docs/TROUBLESHOOTING.md

@@ -0,0 +1,285 @@
+# Troubleshooting Guide
+
+## Common Issues
+
+### Configuration Issues
+
+#### Configuration File Not Found
+
+**Problem:** Module doesn't load configuration
+
+**Solution:**
+1. Ensure file is at `.augment/go-config.json`
+2. Check file permissions (must be readable)
+3. Verify JSON syntax is valid
+
+```bash
+# Validate JSON syntax
+cat .augment/go-config.json | jq .
+```
+
+#### Invalid Category Name
+
+**Problem:** Category not recognized
+
+**Solution:**
+Valid categories are:
+- `web`
+- `microservices`
+- `cli`
+- `cloud`
+- `distributed`
+- `devops`
+- `api`
+
+Check spelling and case sensitivity.
+
+---
+
+### Rule Application Issues
+
+#### Rules Not Being Applied
+
+**Problem:** AI not following Go standards
+
+**Solution:**
+1. Verify `rules.enabled` is `true` in configuration
+2. Check category selection matches your project type
+3. Ensure rule files exist in `rules/` directory
+4. Verify module is loaded in Augment Extensions
+
+#### Conflicting Rules
+
+**Problem:** Multiple categories have conflicting guidance
+
+**Solution:**
+1. Universal rules always apply first
+2. Category-specific rules override when conflicts occur
+3. Later categories in the list take precedence
+4. Consider using fewer, more specific categories
+
+---
+
+### Static Analysis Issues
+
+#### golangci-lint Not Running
+
+**Problem:** Linter not executing
+
+**Solution:**
+```bash
+# Install golangci-lint
+go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
+
+# Verify installation
+golangci-lint --version
+
+# Run manually
+golangci-lint run
+```
+
+#### go vet Errors
+
+**Problem:** `go vet` reports issues
+
+**Solution:**
+```bash
+# Run go vet to see specific issues
+go vet ./...
+
+# Common fixes:
+# - Remove unused variables
+# - Fix Printf format strings
+# - Address suspicious constructs
+```
+
+---
+
+### Example Validation Issues
+
+#### Examples Don't Compile
+
+**Problem:** Example code fails to build
+
+**Solution:**
+```bash
+# Check Go version (requires 1.18+)
+go version
+
+# Update dependencies
+go mod tidy
+
+# Build specific example
+go build examples/web/http-server.go
+```
+
+#### Formatting Issues
+
+**Problem:** Code not properly formatted
+
+**Solution:**
+```bash
+# Format all Go files
+gofmt -w .
+
+# Or use goimports (includes import management)
+goimports -w .
+```
+
+---
+
+### Integration Issues
+
+#### Module Not Appearing in Augment
+
+**Problem:** Module not visible in Augment Extensions
+
+**Solution:**
+1. Verify `module.json` exists and is valid
+2. Check module is in `augment-extensions/coding-standards/go/`
+3. Restart Augment Code AI
+4. Check Augment Extensions catalog
+
+#### AI Not Using Templates
+
+**Problem:** Generated code doesn't follow templates
+
+**Solution:**
+1. Verify templates exist in `templates/` directory
+2. Check template format matches specification
+3. Ensure category is selected in configuration
+4. Try regenerating with explicit category mention
+
+---
+
+### Performance Issues
+
+#### Slow Rule Loading
+
+**Problem:** Module takes long to load
+
+**Solution:**
+1. Reduce number of selected categories
+2. Disable unused static analysis tools
+3. Check for large rule files (should be < 5KB each)
+
+---
+
+### Testing Issues
+
+#### Unit Tests Failing
+
+**Problem:** Module tests don't pass
+
+**Solution:**
+```bash
+# Run tests with verbose output
+npm test -- --reporter=verbose
+
+# Run specific test file
+npm test tests/unit/module-structure.test.ts
+
+# Check test dependencies
+npm install
+```
+
+#### Integration Tests Failing
+
+**Problem:** Integration tests fail
+
+**Solution:**
+1. Verify all required files exist
+2. Check file permissions
+3. Ensure module structure matches specification
+4. Review test output for specific failures
+
+---
+
+## Getting Help
+
+### Check Documentation
+
+1. [README.md](../README.md) - Module overview
+2. [CONFIGURATION.md](./CONFIGURATION.md) - Configuration guide
+3. [CATEGORIES.md](./CATEGORIES.md) - Category details
+
+### Validate Your Setup
+
+```bash
+# Run validation script
+./tests/validate-examples.sh
+
+# Or on Windows
+.\tests\validate-examples.ps1
+```
+
+### Debug Mode
+
+Enable verbose logging:
+
+```json
+{
+  "debug": true,
+  "logging": {
+    "level": "debug"
+  }
+}
+```
+
+### Report Issues
+
+If problems persist:
+1. Check existing issues in repository
+2. Gather error messages and logs
+3. Include configuration file
+4. Describe expected vs actual behavior
+5. Submit issue with details
+
+---
+
+## Best Practices
+
+### Avoid Common Mistakes
+
+1. **Don't mix too many categories** - Use 2-3 maximum
+2. **Don't disable universal rules** - They're essential
+3. **Don't skip static analysis** - Catches issues early
+4. **Don't ignore warnings** - They indicate potential problems
+
+### Recommended Workflow
+
+1. Start with single category
+2. Add universal rules
+3. Enable static analysis
+4. Test with examples
+5. Gradually add more categories if needed
+
+---
+
+## Quick Fixes
+
+### Reset Configuration
+
+```bash
+# Remove configuration
+rm .augment/go-config.json
+
+# Use default configuration
+cp augment-extensions/coding-standards/go/config/examples/web-service.json .augment/go-config.json
+```
+
+### Reinstall Module
+
+```bash
+# Remove and reinstall
+rm -rf augment-extensions/coding-standards/go
+git checkout augment-extensions/coding-standards/go
+```
+
+### Clear Cache
+
+```bash
+# Clear Augment cache (if applicable)
+rm -rf .augment/cache
+```
+

package/augment-extensions/coding-standards/go/examples/cli/cobra-app.go

@@ -0,0 +1,287 @@
+// Package main demonstrates a production-ready CLI application using Cobra and Viper
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/viper"
+)
+
+var (
+	cfgFile string
+	verbose bool
+)
+
+// Config represents application configuration
+type Config struct {
+	Server ServerConfig `mapstructure:"server"`
+	Log    LogConfig    `mapstructure:"log"`
+}
+
+type ServerConfig struct {
+	Host string `mapstructure:"host"`
+	Port int    `mapstructure:"port"`
+}
+
+type LogConfig struct {
+	Level  string `mapstructure:"level"`
+	Format string `mapstructure:"format"`
+}
+
+// rootCmd represents the base command
+var rootCmd = &cobra.Command{
+	Use:   "myapp",
+	Short: "A production-ready CLI application",
+	Long: `myapp is a CLI application demonstrating best practices for
+command-line tools in Go using Cobra and Viper.`,
+}
+
+// versionCmd represents the version command
+var versionCmd = &cobra.Command{
+	Use:   "version",
+	Short: "Print the version number",
+	Run: func(cmd *cobra.Command, args []string) {
+		fmt.Println("myapp v1.0.0")
+	},
+}
+
+// configCmd represents the config command group
+var configCmd = &cobra.Command{
+	Use:   "config",
+	Short: "Manage configuration",
+}
+
+// configShowCmd shows current configuration
+var configShowCmd = &cobra.Command{
+	Use:   "show",
+	Short: "Show current configuration",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		cfg, err := loadConfig()
+		if err != nil {
+			return err
+		}
+
+		fmt.Printf("Configuration:\n")
+		fmt.Printf("  Server Host: %s\n", cfg.Server.Host)
+		fmt.Printf("  Server Port: %d\n", cfg.Server.Port)
+		fmt.Printf("  Log Level:   %s\n", cfg.Log.Level)
+		fmt.Printf("  Log Format:  %s\n", cfg.Log.Format)
+
+		return nil
+	},
+}
+
+// configInitCmd generates a sample config file
+var configInitCmd = &cobra.Command{
+	Use:   "init",
+	Short: "Generate sample configuration file",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		home, err := os.UserHomeDir()
+		if err != nil {
+			return err
+		}
+
+		configPath := filepath.Join(home, ".myapp", "config.yaml")
+
+		// Create directory
+		if err := os.MkdirAll(filepath.Dir(configPath), 0755); err != nil {
+			return err
+		}
+
+		// Set defaults
+		viper.SetDefault("server.host", "localhost")
+		viper.SetDefault("server.port", 8080)
+		viper.SetDefault("log.level", "info")
+		viper.SetDefault("log.format", "json")
+
+		// Write config
+		if err := viper.WriteConfigAs(configPath); err != nil {
+			return err
+		}
+
+		fmt.Printf("Configuration file created: %s\n", configPath)
+		return nil
+	},
+}
+
+// serverCmd represents the server command group
+var serverCmd = &cobra.Command{
+	Use:   "server",
+	Short: "Server operations",
+}
+
+// serverStartCmd starts the server
+var serverStartCmd = &cobra.Command{
+	Use:   "start",
+	Short: "Start the server",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		cfg, err := loadConfig()
+		if err != nil {
+			return err
+		}
+
+		if verbose {
+			fmt.Printf("Starting server on %s:%d\n", cfg.Server.Host, cfg.Server.Port)
+		}
+
+		// Server start logic would go here
+		fmt.Println("Server started successfully")
+		return nil
+	},
+}
+
+// userCmd represents the user command group
+var userCmd = &cobra.Command{
+	Use:   "user",
+	Short: "User management",
+}
+
+var (
+	userEmail string
+	userRole  string
+)
+
+// userCreateCmd creates a new user
+var userCreateCmd = &cobra.Command{
+	Use:   "create [name]",
+	Short: "Create a new user",
+	Args:  cobra.ExactArgs(1),
+	Example: `  # Create a user with email
+  myapp user create john --email john@example.com
+  
+  # Create an admin user
+  myapp user create admin --email admin@example.com --role admin`,
+	PreRunE: func(cmd *cobra.Command, args []string) error {
+		// Validate name
+		name := args[0]
+		if len(name) < 3 {
+			return fmt.Errorf("name must be at least 3 characters")
+		}
+
+		// Validate email
+		if userEmail == "" {
+			return fmt.Errorf("email is required")
+		}
+
+		return nil
+	},
+	RunE: func(cmd *cobra.Command, args []string) error {
+		name := args[0]
+
+		if verbose {
+			fmt.Printf("Creating user: %s (%s) with role: %s\n", name, userEmail, userRole)
+		}
+
+		// User creation logic would go here
+		fmt.Printf("User '%s' created successfully\n", name)
+		return nil
+	},
+}
+
+// userListCmd lists all users
+var userListCmd = &cobra.Command{
+	Use:   "list",
+	Short: "List all users",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		if verbose {
+			fmt.Println("Fetching users...")
+		}
+
+		// List users logic would go here
+		fmt.Println("Users:")
+		fmt.Println("  1. john (john@example.com)")
+		fmt.Println("  2. jane (jane@example.com)")
+
+		return nil
+	},
+}
+
+func init() {
+	cobra.OnInitialize(initConfig)
+
+	// Global flags
+	rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.myapp/config.yaml)")
+	rootCmd.PersistentFlags().BoolVarP(&verbose, "verbose", "v", false, "verbose output")
+
+	// Add commands
+	rootCmd.AddCommand(versionCmd)
+	rootCmd.AddCommand(configCmd)
+	rootCmd.AddCommand(serverCmd)
+	rootCmd.AddCommand(userCmd)
+
+	// Config subcommands
+	configCmd.AddCommand(configShowCmd)
+	configCmd.AddCommand(configInitCmd)
+
+	// Server subcommands
+	serverCmd.AddCommand(serverStartCmd)
+
+	// User subcommands
+	userCmd.AddCommand(userCreateCmd)
+	userCmd.AddCommand(userListCmd)
+
+	// User create flags
+	userCreateCmd.Flags().StringVar(&userEmail, "email", "", "user email (required)")
+	userCreateCmd.Flags().StringVar(&userRole, "role", "user", "user role (user, admin)")
+	userCreateCmd.MarkFlagRequired("email")
+}
+
+func initConfig() {
+	if cfgFile != "" {
+		viper.SetConfigFile(cfgFile)
+	} else {
+		home, err := os.UserHomeDir()
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+			os.Exit(1)
+		}
+
+		viper.AddConfigPath(filepath.Join(home, ".myapp"))
+		viper.AddConfigPath(".")
+		viper.SetConfigName("config")
+		viper.SetConfigType("yaml")
+	}
+
+	// Environment variables
+	viper.SetEnvPrefix("MYAPP")
+	viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
+	viper.AutomaticEnv()
+
+	// Set defaults
+	viper.SetDefault("server.host", "localhost")
+	viper.SetDefault("server.port", 8080)
+	viper.SetDefault("log.level", "info")
+	viper.SetDefault("log.format", "json")
+
+	// Read config file (ignore if not found)
+	if err := viper.ReadInConfig(); err != nil {
+		if _, ok := err.(viper.ConfigFileNotFoundError); !ok {
+			fmt.Fprintf(os.Stderr, "Error reading config: %v\n", err)
+		}
+	}
+}
+
+func loadConfig() (*Config, error) {
+	var cfg Config
+	if err := viper.Unmarshal(&cfg); err != nil {
+		return nil, fmt.Errorf("failed to unmarshal config: %w", err)
+	}
+
+	// Validate
+	if cfg.Server.Port < 1 || cfg.Server.Port > 65535 {
+		return nil, fmt.Errorf("invalid port: %d", cfg.Server.Port)
+	}
+
+	return &cfg, nil
+}
+
+func main() {
+	if err := rootCmd.Execute(); err != nil {
+		os.Exit(1)
+	}
+}
+