@mytechtoday/augment-extensions 1.4.0 → 1.5.0

package/augment-extensions/coding-standards/go/rules/categories/distributed-systems/event-sourcing.md

@@ -0,0 +1,246 @@
+# Event Sourcing Rules
+
+## Overview
+
+Best practices for implementing event sourcing patterns in Go applications including event stores, projections, and CQRS.
+
+## Rules
+
+### 1. Design Immutable Events
+
+**Rule**: Events should be immutable and contain all necessary information.
+
+**Good Example**:
+```go
+type Event struct {
+    ID          string    `json:"id"`
+    AggregateID string    `json:"aggregate_id"`
+    Type        string    `json:"type"`
+    Data        json.RawMessage `json:"data"`
+    Metadata    map[string]string `json:"metadata"`
+    Timestamp   time.Time `json:"timestamp"`
+    Version     int       `json:"version"`
+}
+
+type UserCreatedEvent struct {
+    UserID    string `json:"user_id"`
+    Email     string `json:"email"`
+    Name      string `json:"name"`
+    CreatedAt time.Time `json:"created_at"`
+}
+
+func NewUserCreatedEvent(userID, email, name string) (*Event, error) {
+    data, err := json.Marshal(UserCreatedEvent{
+        UserID:    userID,
+        Email:     email,
+        Name:      name,
+        CreatedAt: time.Now(),
+    })
+    if err != nil {
+        return nil, err
+    }
+    
+    return &Event{
+        ID:          uuid.New().String(),
+        AggregateID: userID,
+        Type:        "UserCreated",
+        Data:        data,
+        Timestamp:   time.Now(),
+        Version:     1,
+    }, nil
+}
+```
+
+### 2. Implement Event Store Interface
+
+**Rule**: Define a clear event store interface for persistence.
+
+**Good Example**:
+```go
+type EventStore interface {
+    Save(ctx context.Context, events []Event) error
+    Load(ctx context.Context, aggregateID string) ([]Event, error)
+    LoadFrom(ctx context.Context, aggregateID string, version int) ([]Event, error)
+    Subscribe(ctx context.Context, eventTypes []string) (<-chan Event, error)
+}
+
+type PostgresEventStore struct {
+    db *sql.DB
+}
+
+func (s *PostgresEventStore) Save(ctx context.Context, events []Event) error {
+    tx, err := s.db.BeginTx(ctx, nil)
+    if err != nil {
+        return err
+    }
+    defer tx.Rollback()
+    
+    for _, event := range events {
+        _, err := tx.ExecContext(ctx,
+            `INSERT INTO events (id, aggregate_id, type, data, metadata, timestamp, version)
+             VALUES ($1, $2, $3, $4, $5, $6, $7)`,
+            event.ID, event.AggregateID, event.Type, event.Data,
+            event.Metadata, event.Timestamp, event.Version,
+        )
+        if err != nil {
+            return err
+        }
+    }
+    
+    return tx.Commit()
+}
+```
+
+### 3. Implement Aggregate Root Pattern
+
+**Rule**: Use aggregate roots to ensure consistency boundaries.
+
+**Good Example**:
+```go
+type User struct {
+    ID      string
+    Email   string
+    Name    string
+    Version int
+    changes []Event
+}
+
+func (u *User) ApplyEvent(event Event) error {
+    switch event.Type {
+    case "UserCreated":
+        var data UserCreatedEvent
+        if err := json.Unmarshal(event.Data, &data); err != nil {
+            return err
+        }
+        u.ID = data.UserID
+        u.Email = data.Email
+        u.Name = data.Name
+        
+    case "UserEmailChanged":
+        var data UserEmailChangedEvent
+        if err := json.Unmarshal(event.Data, &data); err != nil {
+            return err
+        }
+        u.Email = data.NewEmail
+    }
+    
+    u.Version = event.Version
+    return nil
+}
+
+func (u *User) ChangeEmail(newEmail string) error {
+    if newEmail == u.Email {
+        return fmt.Errorf("email unchanged")
+    }
+    
+    event, err := NewUserEmailChangedEvent(u.ID, u.Email, newEmail)
+    if err != nil {
+        return err
+    }
+    
+    u.changes = append(u.changes, *event)
+    return u.ApplyEvent(*event)
+}
+
+func (u *User) GetUncommittedChanges() []Event {
+    return u.changes
+}
+
+func (u *User) MarkChangesAsCommitted() {
+    u.changes = nil
+}
+```
+
+### 4. Build Projections for Read Models
+
+**Rule**: Create separate read models (projections) from events.
+
+**Good Example**:
+```go
+type UserProjection struct {
+    ID        string
+    Email     string
+    Name      string
+    CreatedAt time.Time
+    UpdatedAt time.Time
+}
+
+type ProjectionBuilder struct {
+    db *sql.DB
+}
+
+func (pb *ProjectionBuilder) HandleEvent(ctx context.Context, event Event) error {
+    switch event.Type {
+    case "UserCreated":
+        return pb.handleUserCreated(ctx, event)
+    case "UserEmailChanged":
+        return pb.handleUserEmailChanged(ctx, event)
+    }
+    return nil
+}
+
+func (pb *ProjectionBuilder) handleUserCreated(ctx context.Context, event Event) error {
+    var data UserCreatedEvent
+    if err := json.Unmarshal(event.Data, &data); err != nil {
+        return err
+    }
+    
+    _, err := pb.db.ExecContext(ctx,
+        `INSERT INTO user_projections (id, email, name, created_at, updated_at)
+         VALUES ($1, $2, $3, $4, $5)`,
+        data.UserID, data.Email, data.Name, data.CreatedAt, time.Now(),
+    )
+    return err
+}
+```
+
+### 5. Implement Event Versioning
+
+**Rule**: Support event schema evolution with versioning.
+
+**Good Example**:
+```go
+type EventUpgrader interface {
+    Upgrade(event Event) (Event, error)
+}
+
+type UserCreatedV1ToV2 struct{}
+
+func (u *UserCreatedV1ToV2) Upgrade(event Event) (Event, error) {
+    if event.Version != 1 {
+        return event, nil
+    }
+    
+    var v1Data struct {
+        UserID string `json:"user_id"`
+        Email  string `json:"email"`
+    }
+    
+    if err := json.Unmarshal(event.Data, &v1Data); err != nil {
+        return event, err
+    }
+    
+    v2Data := UserCreatedEvent{
+        UserID:    v1Data.UserID,
+        Email:     v1Data.Email,
+        Name:      "Unknown", // Default for missing field
+        CreatedAt: event.Timestamp,
+    }
+    
+    data, err := json.Marshal(v2Data)
+    if err != nil {
+        return event, err
+    }
+    
+    event.Data = data
+    event.Version = 2
+    
+    return event, nil
+}
+```
+
+## References
+
+- [Event Sourcing Pattern](https://martinfowler.com/eaaDev/EventSourcing.html)
+- [CQRS Pattern](https://martinfowler.com/bliki/CQRS.html)
+

package/augment-extensions/coding-standards/go/rules/cli/command-parsing.md

@@ -0,0 +1,264 @@
+# Go CLI Tools - Command Parsing
+
+## Overview
+
+Command parsing is fundamental to CLI tools. This document defines best practices for implementing command-line interfaces using Cobra in Go.
+
+## Core Principles
+
+1. **User Experience**: Provide clear help text and examples
+2. **Subcommands**: Organize functionality into logical subcommands
+3. **Flags**: Use flags for options and arguments for required inputs
+4. **Validation**: Validate inputs early and provide helpful error messages
+5. **Consistency**: Follow Unix conventions for CLI design
+
+## Rules
+
+### GOL.3.3.1.1: Use Cobra for Command Parsing
+
+**Rule**: Use Cobra library for building CLI applications with subcommands.
+
+**Severity**: WARNING
+
+**Rationale**: Cobra provides robust command parsing, help generation, and follows CLI best practices.
+
+**✅ Good**:
+```go
+import (
+    "github.com/spf13/cobra"
+)
+
+var rootCmd = &cobra.Command{
+    Use:   "myapp",
+    Short: "A brief description of your application",
+    Long: `A longer description that spans multiple lines and likely contains
+examples and usage of using your application.`,
+}
+
+var versionCmd = &cobra.Command{
+    Use:   "version",
+    Short: "Print the version number",
+    Run: func(cmd *cobra.Command, args []string) {
+        fmt.Println("myapp v1.0.0")
+    },
+}
+
+func init() {
+    rootCmd.AddCommand(versionCmd)
+}
+
+func Execute() error {
+    return rootCmd.Execute()
+}
+
+func main() {
+    if err := Execute(); err != nil {
+        os.Exit(1)
+    }
+}
+```
+
+### GOL.3.3.1.2: Organize Commands with Subcommands
+
+**Rule**: Use subcommands to organize related functionality.
+
+**Severity**: INFO
+
+**Rationale**: Subcommands provide clear organization and discoverability.
+
+**✅ Good**:
+```go
+var userCmd = &cobra.Command{
+    Use:   "user",
+    Short: "Manage users",
+}
+
+var userListCmd = &cobra.Command{
+    Use:   "list",
+    Short: "List all users",
+    Run: func(cmd *cobra.Command, args []string) {
+        // List users
+    },
+}
+
+var userCreateCmd = &cobra.Command{
+    Use:   "create [name]",
+    Short: "Create a new user",
+    Args:  cobra.ExactArgs(1),
+    Run: func(cmd *cobra.Command, args []string) {
+        name := args[0]
+        // Create user
+    },
+}
+
+func init() {
+    userCmd.AddCommand(userListCmd)
+    userCmd.AddCommand(userCreateCmd)
+    rootCmd.AddCommand(userCmd)
+}
+
+// Usage:
+// myapp user list
+// myapp user create john
+```
+
+### GOL.3.3.1.3: Define Flags with Appropriate Types
+
+**Rule**: Use typed flags (string, int, bool) and provide default values.
+
+**Severity**: ERROR
+
+**Rationale**: Type safety prevents runtime errors and improves user experience.
+
+**✅ Good**:
+```go
+var (
+    outputFormat string
+    verbose      bool
+    maxResults   int
+)
+
+var listCmd = &cobra.Command{
+    Use:   "list",
+    Short: "List resources",
+    Run: func(cmd *cobra.Command, args []string) {
+        if verbose {
+            fmt.Println("Verbose mode enabled")
+        }
+        fmt.Printf("Output format: %s, Max results: %d\n", outputFormat, maxResults)
+    },
+}
+
+func init() {
+    // String flag with default
+    listCmd.Flags().StringVarP(&outputFormat, "output", "o", "table", "Output format (table, json, yaml)")
+    
+    // Boolean flag
+    listCmd.Flags().BoolVarP(&verbose, "verbose", "v", false, "Enable verbose output")
+    
+    // Integer flag with default
+    listCmd.Flags().IntVarP(&maxResults, "limit", "l", 10, "Maximum number of results")
+    
+    // Required flag
+    listCmd.MarkFlagRequired("output")
+}
+```
+
+### GOL.3.3.1.4: Validate Arguments and Flags
+
+**Rule**: Validate command arguments and flags before execution.
+
+**Severity**: ERROR
+
+**Rationale**: Early validation provides clear error messages and prevents invalid operations.
+
+**✅ Good**:
+```go
+var createCmd = &cobra.Command{
+    Use:   "create [name]",
+    Short: "Create a resource",
+    Args:  cobra.ExactArgs(1),
+    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 flag
+        if outputFormat != "json" && outputFormat != "yaml" {
+            return fmt.Errorf("invalid output format: %s", outputFormat)
+        }
+        
+        return nil
+    },
+    RunE: func(cmd *cobra.Command, args []string) error {
+        name := args[0]
+        return createResource(name)
+    },
+}
+
+// Cobra built-in validators
+var exactOneArg = &cobra.Command{
+    Args: cobra.ExactArgs(1),
+}
+
+var minTwoArgs = &cobra.Command{
+    Args: cobra.MinimumNArgs(2),
+}
+
+var maxThreeArgs = &cobra.Command{
+    Args: cobra.MaximumNArgs(3),
+}
+
+var rangeArgs = &cobra.Command{
+    Args: cobra.RangeArgs(1, 3),
+}
+```
+
+### GOL.3.3.1.5: Provide Helpful Usage Examples
+
+**Rule**: Include usage examples in command help text.
+
+**Severity**: WARNING
+
+**Rationale**: Examples improve discoverability and reduce user confusion.
+
+**✅ Good**:
+```go
+var deployCmd = &cobra.Command{
+    Use:   "deploy [app-name]",
+    Short: "Deploy an application",
+    Long: `Deploy an application to the specified environment.
+    
+The deploy command builds and deploys your application to the target environment.
+It supports multiple deployment strategies and configuration options.`,
+    Example: `  # Deploy to production
+  myapp deploy myapp --env production
+  
+  # Deploy with custom config
+  myapp deploy myapp --env staging --config custom.yaml
+  
+  # Deploy with verbose output
+  myapp deploy myapp --env dev -v`,
+    Args: cobra.ExactArgs(1),
+    RunE: func(cmd *cobra.Command, args []string) error {
+        appName := args[0]
+        return deployApp(appName)
+    },
+}
+```
+
+### GOL.3.3.1.6: Use Persistent Flags for Global Options
+
+**Rule**: Use persistent flags for options that apply to all subcommands.
+
+**Severity**: INFO
+
+**✅ Good**:
+```go
+var (
+    configFile string
+    verbose    bool
+)
+
+func init() {
+    // Persistent flags available to all subcommands
+    rootCmd.PersistentFlags().StringVar(&configFile, "config", "", "config file (default is $HOME/.myapp.yaml)")
+    rootCmd.PersistentFlags().BoolVarP(&verbose, "verbose", "v", false, "verbose output")
+    
+    // Local flags only for this command
+    rootCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
+}
+
+// Usage:
+// myapp --verbose user list    # verbose applies to all commands
+// myapp user list --verbose    # also works
+```
+
+## References
+
+- [Cobra Documentation](https://github.com/spf13/cobra)
+- [CLI Best Practices](https://clig.dev/)
+- [POSIX Utility Conventions](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html)
+