# AGENTS.md - RSSuper Development Guide

This file provides guidelines for AI agents working on the RSSuper codebase.

## Project Overview

RSSuper is a native multi-platform RSS reader:
- **iOS/macOS**: Swift + SwiftUI + Xcode
- **Android**: Kotlin + Jetpack Compose + Gradle
- **Linux**: Vala + GTK4 + Libadwaita + Meson
- **Windows**: Planned (C# + WinUI3)

## Build Commands

### Main Build Script (all platforms)
```bash
./scripts/build.sh                           # Build all platforms (debug)
./scripts/build.sh -p ios,android            # Build specific platforms
./scripts/build.sh -t release                # Release build
./scripts/build.sh --test                    # Build and test
./scripts/build.sh -a clean                  # Clean all
```

### iOS/macOS
```bash
./scripts/build-ios.sh                       # Debug build
./scripts/build-ios.sh Release iOS build     # Release build
./scripts/build-ios.sh Debug iOS test         # Run tests
./scripts/build-ios.sh Debug iOS clean        # Clean

# Single test file (in Xcode)
xcodebuild test -scheme RSSuper -destination 'platform=iOS Simulator,name=iPhone 15' \
  -only-testing:RSSuperTests/SearchQueryTests
```

### Android
```bash
cd android && ./gradlew assembleDebug       # Debug APK
cd android && ./gradlew assembleRelease     # Release APK
cd android && ./gradlew test                 # Run all unit tests
cd android && ./gradlew test --tests "com.rssuper.search.SearchQueryTest"  # Single test class
cd android && ./gradlew clean                # Clean

# Single test via Gradle
cd android && ./gradlew test --tests "com.rssuper.search.SearchQueryTest.testParse*"
```

### Linux
```bash
./scripts/build-linux.sh debug build         # Debug build
./scripts/build-linux.sh release test        # Run tests
./scripts/build-linux.sh debug clean          # Clean
```

## Code Style Guidelines

### General Principles
- Write clean, readable code with minimal comments (only when logic is complex)
- Follow existing patterns in each platform's codebase
- Use dependency injection for testability
- Prefer explicit over implicit

### Kotlin (Android)
- **Formatting**: 4 spaces indentation, 140 char line limit
- **Naming**: `camelCase` for functions/variables, `PascalCase` for classes
- **Imports**: Grouped: standard library → Android → third-party → project
- **Types**: Use Kotlin null safety, prefer `val` over `var`
- **Error Handling**: Use `Result<T>` or sealed classes for errors (see `SearchQuery.kt`)
- **Coroutines**: Use `viewModelScope` in ViewModels, structured concurrency
- **Tests**: JUnit 4 with Mockito, Robolectric for Android-specific tests

### Swift (iOS/macOS)
- **Formatting**: 4 spaces, 120 char line limit
- **Naming**: `camelCase`, `PascalCase` for types/protocols
- **Imports**: Foundation → SwiftUI/AppKit → third-party → project
- **Error Handling**: Use `Result<T, Error>` and `async/await`
- **Protocols**: Use protocols for dependency injection (see `FeedServiceProtocol`)
- **Tests**: XCTest, arrange/act/assert pattern

### Vala (Linux)
- **Formatting**: 4 spaces indentation
- **Naming**: `snake_case` for methods/variables, `PascalCase` for classes
- **Memory**: Use GLib's reference counting (`ref`/`unref`)
- **Error Handling**: Use `GLib.Error` and `try/catch`

### Android-specific
- **ViewModels**: Use `androidx.lifecycle.ViewModel` with `StateFlow`
- **Database**: Room with Kotlin coroutines
- **Background Work**: WorkManager for sync tasks

### iOS-specific
- **State Management**: `@Observable` macro (iOS 17+) or `ObservableObject`
- **Persistence**: SQLite via SQLite.swift
- **Background**: BGTaskScheduler for background refresh

## Architecture Patterns

### Clean Architecture Layers
1. **UI Layer**: SwiftUI Views / Jetpack Compose
2. **ViewModel/ViewModel**: Business logic, state management
3. **Service Layer**: `FeedService`, `SearchService`, `BookmarkStore`
4. **Data Layer**: Database managers, network clients

### Dependency Injection
- Android: Manual DI in constructors (no framework)
- iOS: Protocol-based DI with default implementations

## Testing Guidelines

### Unit Tests Location
- **Android**: `android/src/test/java/com/rssuper/`
- **iOS**: `iOS/RSSuperTests/`
- **Linux**: Test files alongside source in `linux/src/`

### Test Naming Convention
- `MethodName_State_ExpectedResult` (e.g., `SearchQueryTest.parseEmptyQueryReturnsNull`)

### Test Data
- Fixtures in `tests/fixtures/` (sample RSS/Atom feeds)

## File Organization

```
RSSuper/
├── android/                    # Kotlin Android library
│   ├── src/main/java/com/rssuper/
│   │   ├── model/             # Data models
│   │   ├── parsing/           # Feed parsers
│   │   ├── state/             # State management
│   │   ├── viewmodel/         # ViewModels
│   │   ├── search/            # Search service
│   │   └── database/          # Room database
│   └── src/test/              # Unit tests
├── iOS/RSSuper/               # Swift iOS app
│   ├── Models/                # Data models
│   ├── Parsing/               # Feed parsers
│   ├── Services/              # Business logic
│   ├── ViewModels/            # ViewModels
│   ├── Networking/            # HTTP client
│   ├── Settings/              # User preferences
│   └── Database/              # SQLite layer
├── iOS/RSSuperTests/          # Unit tests
├── linux/                     # Vala GTK app
│   └── src/                   # Source + tests
├── scripts/                   # Build scripts
└── tests/fixtures/           # Test data
```

## Common Tasks

### Running a Single Android Test
```bash
cd android
./gradlew test --tests "com.rssuper.search.SearchQueryTest"
```

### Running a Single iOS Test
```bash
./scripts/build-ios.sh Debug iOS test
# Or in Xcode: Product > Run Tests (select specific test)
```

### Adding a New Platform Module
1. Create directory under `native-route/`
2. Add build command to `./scripts/build.sh`
3. Add test configuration to CI workflow
4. Update this AGENTS.md

## Important Notes

- The Android project uses a library module structure (not application)
- iOS minimum deployment: iOS 16.0+
- Android minimum SDK: 24 (Android 7.0)
- Linux requires GTK4, Libadwaita, SQLite3 development headers
- All platform modules share similar business logic patterns