86 lines
3.6 KiB
Markdown
86 lines
3.6 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
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.
|