Michael Freno
b79e6e7aa2
Some checks failed
CI - Multi-Platform Native / Build iOS (RSSuper) (push) Has been cancelled
CI - Multi-Platform Native / Build macOS (push) Has been cancelled
CI - Multi-Platform Native / Build Android (push) Has been cancelled
CI - Multi-Platform Native / Build Linux (push) Has been cancelled
CI - Multi-Platform Native / Integration Tests (push) Has been cancelled
CI - Multi-Platform Native / Build Summary (push) Has been cancelled
175 lines
6.3 KiB
Markdown
175 lines
6.3 KiB
Markdown
# 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 |