lazyazure: Instructions file for Codex

LazyAzure - Agent Guidelines

This document provides guidelines and lessons learned for agents working on the LazyAzure codebase.

Project Overview

LazyAzure is a TUI (Terminal User Interface) application for Azure resource management, inspired by lazydocker. It uses:

• gocui for the terminal interface
• Azure SDK for Go for Azure API interactions
• DefaultAzureCredential for authentication (supports multiple auth methods)

Critical Guidelines

1. TUI Development with gocui

Event Loop and Threading

• CRITICAL: Never hold locks (mutex) when calling gocui operations
• CRITICAL: Never call gui.g.Update() or gui.g.UpdateAsync() while holding a lock
• Use go func() for async operations, then use gui.g.UpdateAsync() for UI updates
• UpdateAsync() is safer than Update() as it doesn't spawn a goroutine

Cursor Handling

• Use v.SetCursor(x, y) directly instead of v.TextArea.MoveCursorDown/Up
• Get cursor position with v.Cursor() which returns (x, y)
• Don't mix cursor tracking with origin/offset calculations unless necessary

View Management

• Use gocui.IsUnknownView(err) to check if a view already exists
• Views are identified by string names (e.g., "subscriptions", "resourcegroups")
• Set current view with gui.g.SetCurrentView("viewname")

2. Mutex Best Practices

Deadlock Prevention

// ❌ WRONG: Holding lock while calling another function that needs lock
func (gui *Gui) nextLine() {
    gui.mu.Lock()
    defer gui.mu.Unlock()
    gui.selectItem()  // selectItem() also needs Lock = DEADLOCK!
}

// ✅ CORRECT: Release lock before calling other methods
func (gui *Gui) nextLine() {
    gui.mu.RLock()
    count := len(gui.items)
    gui.mu.RUnlock()
    
    // ... do work ...
    
    gui.selectItem()  // Now safe to acquire Lock
}

Lock Hierarchy

1. RLock() for reading data length/slices
2. Do work without locks
3. Lock() only for updating state
4. Never hold locks during I/O or UI operations