Merge remote-tracking branch 'origin/main' into k0s-1-30

Author: emosbaugh

.cursor/rules/clean-code.mdc

@@ -0,0 +1,44 @@
+---
+description: 
+globs: *.go
+alwaysApply: false
+---
+# Clean Code
+
+Essential clean code principles for Go development in Embedded Cluster.
+
+## File Formatting
+
+### End of File
+- **Always leave a single newline at the end of every file**
+- This ensures proper POSIX compliance and clean git diffs
+
+## Comments
+
+### Keep Comments Concise
+- **Comments should be brief and to the point**
+- Explain *why*, not *what* the code does
+- Avoid redundant comments that just repeat the code
+
+### Comment Quality
+
+- **Write self-explanatory comments that clearly explain the purpose and context**: Explain WHY, not just WHAT the code does
+  ```go
+  // Good - explains WHY and provides context
+  // Retry 3 times because API can be temporarily unavailable during deployment
+  for i := 0; i < 3; i++ {
+      if err := checkAPIHealth(); err == nil {
+          break
+      }
+      time.Sleep(time.Second * 2)
+  }
+  ```
+
+### Function Comments
+- Use concise godoc format for exported functions
+- Focus on purpose and important behavior
+- Single line comments for simple functions
+
+### Inline Comments
+- Use sparingly for complex logic
+- Keep on same line when possible for short explanations

.cursor/rules/frontend-rules.mdc

@@ -1,6 +1,6 @@
 ---
 description: 
-globs: 
+globs: web/*.tsx,web/*.ts,web/*.js,web/*.jsx
 alwaysApply: false
 ---
 # manager experience (front end) rules and guidelines
@@ -43,3 +43,29 @@ alwaysApply: false
 
 
 Please validate and run unit tests with `npm run test:unit <path to file>` from the `web` directory.
+
+## React Architecture Patterns
+
+### Context Usage Guidelines
+
+- **Only use React Context when you have props drilling**: Prefer props for simple parent-child communication to avoid unnecessary complexity
+  ```jsx
+  // Good - simple props for parent-child
+  <ChildComponent isConnected={connected} />
+  
+  // Bad - unnecessary Context for simple cases
+  <ConnectionContext.Provider value={connected}>
+    <ChildComponent />
+  </ConnectionContext.Provider>
+  ```
+
+### Component Visibility Control
+
+- **Control component visibility at parent level, not within the component itself**: This creates cleaner conditional rendering patterns
+  ```jsx
+  // Good - parent controls visibility
+  {showModal && <Modal onClose={() => setShowModal(false)} />}
+  
+  // Bad - component controls its own visibility
+  <Modal visible={showModal} onClose={...} />
+  ```

.cursor/rules/go-best-practices.mdc

@@ -0,0 +1,136 @@
+---
+description: 
+globs: *.go
+alwaysApply: false
+---
+# Go Best Practices
+
+Follow these best practices when writing Go code in this repository.
+
+## Core Principles
+
+- **Clarity and Simplicity**: Write code that is easy to read, understand, and maintain. Favor explicit over implicit.
+- **Dependency Injection**: Use dependency injection to decouple components and enable testing. The functional options pattern is the standard approach.
+- **Interface-Driven Design**: Define behavior through interfaces to enable mocking and loose coupling.
+- **Explicit Error Handling**: Handle all errors explicitly. Use structured error types when appropriate.
+
+## Architecture Patterns
+
+### Functional Options Pattern
+
+Use the functional options pattern for component initialization. This is the standard across controllers and main components.
+
+### Interface Design
+
+- **Small, Focused Interfaces**: Keep interfaces small and focused on specific behavior
+- **Interface Segregation**: Prefer multiple small interfaces over large ones
+- **Testability**: All external dependencies should be behind interfaces for mocking
+- **Naming**: Use descriptive names that indicate the behavior (e.g., `InstallationManager`, `NetUtils`)
+
+## Error Handling
+
+### Error Wrapping and Context
+
+- **Wrap Errors**: Always add context when propagating errors using `fmt.Errorf("operation context: %w", err)`
+- **Use %w verb for error wrapping**: Use `%w` instead of `%v` when wrapping errors to maintain the error chain
+- **Avoid verbose prefixes**: Don't use "failed to" or "unable to" prefixes as they create repetitive error chains
+  ```go
+  return fmt.Errorf("processing config: %w", err)      // Good - concise context
+  return fmt.Errorf("reading config file: %w", err)    // Good - specific context
+  return fmt.Errorf("failed to process config: %w", err)   // Bad - verbose prefix
+  return fmt.Errorf("unable to read config file: %w", err) // Bad - verbose prefix
+  ```
+- **Use gerunds or nouns for context**: Describe the operation being performed
+  ```go
+  return fmt.Errorf("creating directory: %w", err)     // Good - gerund
+  return fmt.Errorf("config validation: %w", err)      // Good - noun
+  return fmt.Errorf("installing component: %w", err)   // Good - gerund
+  ```
+- **Preserve Original**: Store the original error for unwrapping when using custom error types
+- **Meaningful Messages**: Error messages should be actionable and include relevant context without redundant prefixes
+- **Use type-safe error handling**: Check error types instead of string matching to avoid brittle code
+  ```go
+  if errors.Is(err, context.DeadlineExceeded) { ... }  // Good
+  if strings.Contains(err.Error(), "deadline") { ... } // Bad
+  ```
+
+### Error Message Consistency
+
+- **Go error strings should start with lowercase letter and not end with punctuation**: Follow Go conventions
+  ```go
+  return errors.New("failed to connect")     // Good
+  return errors.New("Failed to connect.")   // Bad
+  ```
+
+## Naming Conventions
+
+### Package Names
+- Use short, concise, all-lowercase names
+- Avoid stuttering (don't repeat package name in exported types)
+- Examples: `types`, `utils`, `install`, `auth`
+
+### Types and Functions
+- **Exported Types**: Use `PascalCase` (e.g., `InstallController`, `NetUtils`)
+- **Exported Functions**: Use `PascalCase` (e.g., `NewInstallController`, `ValidateConfig`)
+- **Internal Functions**: Use `camelCase` (e.g., `processRequest`, `validateInput`)
+- **Variables**: Use `camelCase` for all variables
+
+### Interface Naming
+- **Behavior-Based**: Name interfaces after what they do (e.g., `Controller`, `Manager`, `NetUtils`)
+- **Avoid Generic Names**: Don't use generic suffixes like `Interface` unless necessary
+- **Single Method**: For single-method interfaces, consider the "-er" suffix pattern
+
+### Variable Naming Clarity
+
+- **Use distinct variable names for file paths vs configuration objects**: Distinguish between file locations, raw data, and parsed objects
+  ```go
+  configPath := "/etc/config.yaml"  // file location
+  configBytes := []byte{}           // raw data  
+  config := &Config{}               // parsed object
+  ```
+
+## Configuration Management
+
+### Input Validation and Defaults
+
+- **Check before setting defaults**: Always verify if user-provided fields are empty before setting defaults to avoid overriding user input
+  ```go
+  if config.DataDirectory == "" {
+      config.DataDirectory = "/opt/default"
+  }
+  ```
+
+## CLI Design
+
+### Flag Naming and Help
+
+- **Ensure all CLI flags appear in help menu with consistent naming patterns**: Use kebab-case for multi-word flags
+  ```go
+  installCmd.Flags().String("admin-console-namespace", "", "Namespace for admin console")  // Good
+  installCmd.Flags().String("adminconsolenamespace", "", "Namespace for admin console")   // Bad
+  ```
+
+## Concurrency and Thread Safety
+
+### Mutex Usage
+- Use `sync.RWMutex` for read-heavy workloads
+- Keep critical sections small
+- Always use defer for unlocking: `defer mu.Unlock()`
+
+### Context Usage
+- **Context parameter placement**: When added, use `ctx context.Context` as the first parameter
+- **Only add context when it's actually used**: Don't add `context.Context` parameters unless the function will actually use it for cancellation, deadlines, or passing values
+- **Don't store contexts in structs**: Pass them through function calls
+
+## Logging
+
+### Structured Logging with Logrus
+
+- Use `logrus.FieldLogger` interface for dependency injection
+- Add contextual fields to log entries for better debugging
+- Use appropriate log levels: `Debug`, `Info`, `Warn`, `Error`
+
+### Logging Patterns
+
+- **Error Logging**: Always log errors at the outermost caller (bottom of the stack). All the context from the trace should be included in the message wrapping.
+- **Discard Logger**: Use `logger.NewDiscardLogger()` for tests

.cursor/rules/go-ec-api-architecture.mdc

@@ -0,0 +1,127 @@
+---
+description: 
+globs: api/*.go
+alwaysApply: false
+---
+# Go Embedded Cluster API Implementation Guidelines
+
+For comprehensive architecture and package structure details, see [api/README.md](mdc:../api/README.md).
+
+## Essential Implementation Patterns
+
+### Error Handling
+
+#### Structured API Errors
+
+Use structured error types for APIs that need to return detailed error information:
+
+```go
+type APIError struct {
+    StatusCode int         `json:"status_code,omitempty"`
+    Message    string      `json:"message"`
+    Field      string      `json:"field,omitempty"`
+    Errors     []*APIError `json:"errors,omitempty"`
+    err        error       `json:"-"`
+}
+```
+
+#### Error Constructor Functions
+
+Create constructor functions for common API error types.
+
+#### API Error Handling Patterns
+
+- Always log errors with context: `a.logError(r, err, "descriptive message")`
+- Use structured errors: `types.NewBadRequestError(err)`, `types.NewInternalServerError(err)`
+- Wrap errors with context: `fmt.Errorf("operation failed: %w", err)`
+
+#### Specific API Error Types
+
+- **Use specific API error types**: Always use `NewBadRequestError`, `NewInternalServerError`, etc. instead of generic errors for proper HTTP status codes
+  ```go
+  return NewBadRequestError(errors.New("invalid input"))  // Good
+  return errors.New("invalid input")                      // Bad
+  ```
+
+- **Return consistent HTTP status codes**: Use appropriate APIError types for different error conditions
+  ```go
+  return NewBadRequestError(errors.New("invalid input"))        // 400
+  return NewForbiddenError(errors.New("access denied"))         // 403
+  return NewInternalServerError(errors.New("database failed"))  // 500
+  ```
+
+### HTTP Handler Patterns
+
+- Use dedicated Handler structs with HTTP method prefixed names: `func (h *Handler) PostConfigureInstallation(w http.ResponseWriter, r *http.Request) {}`
+- Include HTTP method in handler names: `Get*`, `Post*`, `Put*`, `Delete*`
+- Use helper methods for common operations: `utils.BindJSON`, `utils.JSON`, `utils.JSONError`
+- Always validate input and handle errors appropriately
+
+### Request/Response
+
+- Use `a.bindJSON(w, r, &struct)` for parsing JSON requests
+- Use `a.json(w, r, statusCode, payload)` for success responses
+- Use `a.jsonError(w, r, err)` for error responses
+
+### JSON Tags and Serialization
+
+- Use appropriate JSON tags: `json:"field_name,omitempty"`
+- Use `json:"-"` for fields that shouldn't be serialized
+- Handle both marshaling and unmarshaling in your types
+
+### Dependencies
+
+- Use functional options pattern for initialization
+- Define interfaces for all external dependencies
+- Inject dependencies via constructors
+
+### Manager Architecture (API-Specific)
+
+- **Never inject managers into other managers**: Pass data/config between managers via controller
+- **Controller orchestration**: Controllers read from one manager and pass data to another
+- **Semantic option naming**: Use `WithConfigFile()` for paths, `WithConfigData()` for actual data
+- **Independent testing**: Mock managers separately, test controller orchestration logic independently
+
+```go
+// ✅ CORRECT: Pass data through controller
+configData, err := controller.managerA.GetData()
+controller.managerB = NewManagerB(WithConfigData(configData))
+
+// ❌ INCORRECT: Manager-to-manager injection
+controller.managerB = NewManagerB(WithManagerA(controller.managerA))
+```
+
+### API Documentation
+
+Add Swagger annotations to all handlers for API documentation.
+
+#### Swagger/OpenAPI Requirements
+
+- Use Swagger annotations for HTTP handlers
+- Document request/response structures
+- Include error response documentation
+- Document authentication requirements
+
+## Implementation Quick Reference
+
+### Adding New Functionality
+
+- **New endpoint**: Add handler → create/update controller → define types
+- **New business logic**: Add to appropriate controller or create new manager
+- **New types**: Add to `api/types/` with proper JSON tags
+- **New utilities**: Add to `api/internal/`
+
+### File Naming Conventions
+
+- Handlers: `api/{domain}.go` (e.g., `install.go`, `auth.go`)
+- Controllers: `api/controllers/{domain}/controller.go`
+- Managers: `api/internal/managers/{domain}/manager.go`
+- Types: `api/types/{domain}.go`
+
+### Testing Requirements
+
+- Unit tests: `*_test.go` alongside source files
+- Integration tests: `api/integration/*_test.go`
+- Use table-driven tests with `testify/assert`
+- Mock all external dependencies
+