RSSuper/AGENTS.md

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)

./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

./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

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

./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

cd android
./gradlew test --tests "com.rssuper.search.SearchQueryTest"

Running a Single iOS Test

./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