Go Skills for LlamaFarm CLI

Shared Go best practices for LlamaFarm CLI development. These guidelines ensure idiomatic, maintainable, and secure Go code.

Tech Stack

• Go 1.24+
• Cobra (CLI framework)
• Bubbletea (TUI framework)
• Lipgloss (terminal styling)

Directory Structure

cli/
  cmd/           # Command implementations
    config/      # Configuration types and loading
    orchestrator/ # Service management
    utils/       # Shared utilities
    version/     # Version and upgrade handling
  internal/      # Internal packages
    tui/         # TUI components
    buildinfo/   # Build information

Quick Reference

Error Handling

• Always wrap errors with context: fmt.Errorf("operation failed: %w", err)
• Use sentinel errors for expected conditions: var ErrNotFound = errors.New("not found")
• Check errors immediately after function calls

Concurrency

• Use sync.Mutex for shared state protection
• Use sync.RWMutex when reads dominate writes
• Use channels for goroutine communication
• Always use defer for mutex unlocks

Testing

• Use table-driven tests for comprehensive coverage
• Use interfaces for mockability
• Test file names: *_test.go in same package

Security

• Never log credentials or tokens
• Redact sensitive headers in debug logs
• Validate all external input
• Use context.Context for cancellation

Checklist Files

File	Description
patterns.md	Idiomatic Go patterns
concurrency.md	Goroutines, channels, sync
error-handling.md	Error wrapping, sentinels
testing.md	Table-driven tests, mocks
security.md	Input validation, secure coding

Go Proverbs to Remember

1. "Don't communicate by sharing memory; share memory by communicating"
2. "Errors are values"
3. "A little copying is better than a little dependency"
4. "Clear is better than clever"
5. "Design the architecture, name the components, document the details"

Common Patterns in This Codebase

HTTP Client Interface

type HTTPClient interface {
    Do(req *http.Request) (*http.Response, error)
}

Process Management with Mutex

type ProcessManager struct {
    mu        sync.RWMutex
    processes map[string]*ProcessInfo
}

Cobra Command Pattern

var myCmd = &cobra.Command{
    Use:   "mycommand",
    Short: "Brief description",
    RunE: func(cmd *cobra.Command, args []string) error {
        // Implementation
        return nil
    },
}

Bubbletea Model Pattern

type myModel struct {
    // State fields
}

func (m myModel) Init() tea.Cmd { return nil }
func (m myModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) { /* ... */ }
func (m myModel) View() string { return "" }