flux9s: Instructions file for Codex

flux9s Development Instructions

Core Philosophy

• Zero-maintenance model updates: Use code generation over manual types
• Non-blocking operations: Keep UI responsive with async task spawning
• Graceful degradation: Log errors, don't crash (only panic for truly unrecoverable errors)
• K9s alignment: Follow K9s conventions for keybindings and UX

Before You Start

1. Run just ci after all changes (formats, lints, tests)
2. Large changes require accompanying tests
3. Keys and commands are data: add a key to the action table (src/tui/app/actions.rs) and a command to COMMAND_TABLE (src/tui/app/command_mode.rs) — dispatch, footer, and help all come from those entries. Never add a key arm elsewhere
4. Git operations: User manages their own git workflow. Only use git to restore a single file when explicitly requested (e.g., git restore path/to/file). Never commit, push, create branches, or perform any other git operations

Code Standards

Error Handling

// ✅ Good - Add context to errors
api.patch(name, &params, &patch)
    .await
    .context(format!("Failed to suspend {}/{}", resource_type, name))?;

// ✅ Good - Log errors, return Result
if let Err(e) = operation() {
    tracing::warn!("Operation failed: {}", e);
    return Ok(()); // Continue execution
}

// ❌ Bad - Missing context
api.patch(name, &params, &patch).await?;

// ❌ Bad - Unwrap (use only in tests)
let value = result.unwrap();

State Management

• Use Arc<RwLock<>> only when truly shared across threads
• Prefer simple HashMap/Vec for single-threaded state
• Keep App struct focused - extract complex state into sub-structs

Async Operations

// ✅ Good - Spawn tasks, use channels for results
let (tx, rx) = tokio::sync::oneshot::channel();
self.pending_rx = Some(rx);
tokio::spawn(async move {
    let result = operation().await;
    let _ = tx.send(result);
});

// Later, poll for results
if let Some(result) = app.try_get_result() {
    app.handle_result(result);
}