Comicviewer/AGENTS.md

AGENTS.md

Project Overview

Comicviewer is a desktop comic archive viewer for CachyOS and Arch Linux. It browses local, SMB, FTP, and SFTP locations and opens image files stored in ZIP archives.

Technology

• Rust
• GTK4 with GIO/GVfs for desktop and remote filesystem integration
• SQLite for cached directory metadata, search indexes, and reading history
• AppImage as the primary distribution format
• Korean-first UI with all user-facing strings kept translatable

Core Requirements

• Save local and remote location profiles, including credentials.
• Store credentials as plain text in the application configuration as requested, but restrict the configuration file permissions to 0600.
• Cache remote directory metadata and refresh it asynchronously when browsing.
• Download remote ZIP archives before opening them.
• Limit the persistent ZIP cache with a user-configurable LRU quota. The default is 10 GB. A quota of 0 disables persistent ZIP caching and uses temporary files.
• Support JPEG, PNG, WebP, static GIF, BMP, and AVIF images in ZIP archives.
• Sort archive images and browser entries using natural filename ordering.
• Support ascending and descending sorting by name, modification time, and creation time. Treat unavailable creation times as unknown rather than inventing values.
• Search folder and ZIP names recursively below the current location using the cached index.
• Provide 100%, fit-width, fit-height, two-page, and continuous vertical viewing.
• Support both right-to-left and left-to-right two-page layouts, plus controls that advance by one page to adjust page pairing.
• Save progress per ZIP and save the most recently read ZIP for resume support.

Data Locations

Follow the XDG Base Directory specification:

• Configuration: ${XDG_CONFIG_HOME:-~/.config}/comicviewer/
• Persistent data: ${XDG_DATA_HOME:-~/.local/share}/comicviewer/
• Cache: ${XDG_CACHE_HOME:-~/.cache}/comicviewer/

Do not write application state into the source tree.

Engineering Guidelines

• Prefer the smallest correct implementation and avoid speculative abstractions.
• Keep network and archive work off the GTK main thread.
• Show cached directory data immediately, then update it in the background.
• Use atomic writes for configuration, database migrations, and completed remote downloads. Incomplete downloads must use a distinct temporary suffix.
• Do not extract an entire archive to disk. Decode only requested images and prefetch a small window around the current page.
• Validate archive entry sizes and image dimensions before allocation.
• Never trust archive paths or use them as extraction destinations.
• Preserve errors from GIO, ZIP parsing, and image decoding and present concise, actionable messages in the UI.
• Keep protocol-independent browsing logic separate from GTK widgets.
• Do not introduce credential encryption or keyring integration unless the requirement changes.

Quality Checks

Before considering a change complete, run the checks available in the project, including formatting, linting, and tests. Once the Rust project exists, the minimum expected commands are:

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features

Add focused tests for natural sorting, cache eviction, metadata refresh, archive filtering, reading progress, and remote file change detection.

Git Practices

• Keep commits focused and do not commit generated build output or cached data.
• Do not commit real server addresses, usernames, passwords, or local test configuration.
• Update documentation when runtime dependencies or AppImage requirements change.