57 lines
2.7 KiB
Markdown
57 lines
2.7 KiB
Markdown
|
# AGENTS.md for newsletter-to-web
|
||
|
|
|
||
|
|
This document provides an overview and operational guidance for AI agents working with the `newsletter-to-web` repository, hosted on Gitea.
|
||
|
|
|
||
|
|
## Project Overview
|
||
|
|
|
||
|
|
The `newsletter-to-web` project is a Rust-based command-line application designed to convert email newsletters into a static Atom feed and individual HTML web pages. Its primary goal is to provide a privacy-preserving way to consume newsletters, allowing users to read them in a feed reader or a web browser without tracking elements.
|
||
|
|
|
||
|
|
## Technical Stack
|
||
|
|
|
||
|
|
* **Primary Language:** Rust (evident from `Cargo.toml`, `Cargo.lock`, and crate mentions in the changelog and issues).
|
||
|
|
* **Build System:** Cargo (Rust's package manager and build tool).
|
||
|
|
* **Email Handling:** IMAP protocol for fetching emails.
|
||
|
|
* **Output:** Generates Atom feed (`.xml`) and static HTML files.
|
||
|
|
|
||
|
|
## Key Workflows
|
||
|
|
|
||
|
|
### 1. Initial Setup and Dependencies
|
||
|
|
|
||
|
|
The project uses Cargo. Dependencies are managed via `Cargo.toml` and `Cargo.lock`. A simple `cargo build` should compile the project.
|
||
|
|
|
||
|
|
### 2. Fetching Emails
|
||
|
|
|
||
|
|
Emails are fetched from an IMAP server and stored locally.
|
||
|
|
`newsletter-to-web fetch-from-imap -s <imap.example.com> -u <email@example.com> -p <password>`
|
||
|
|
|
||
|
|
### 3. Building the Feed and HTML Files
|
||
|
|
|
||
|
|
After fetching, the stored emails are processed to generate the Atom feed and HTML pages.
|
||
|
|
`newsletter-to-web --include-html build-feed newsletters.example.org`
|
||
|
|
This command outputs files into the `output/` directory.
|
||
|
|
|
||
|
|
### 4. Running Tests
|
||
|
|
|
||
|
|
(Assumption: Standard Rust test practices apply)
|
||
|
|
To run unit and integration tests:
|
||
|
|
`cargo test`
|
||
|
|
|
||
|
|
## Repository Structure
|
||
|
|
|
||
|
|
* `Cargo.toml`: Project manifest and dependency definitions.
|
||
|
|
* `Cargo.lock`: Exact dependency versions for reproducible builds.
|
||
|
|
* `src/`: Contains the Rust source code.
|
||
|
|
* `main.rs`: Main entry point of the application.
|
||
|
|
* `cli.rs`: Defines command-line interface arguments and subcommands.
|
||
|
|
* `command/`: Contains implementations for various subcommands (e.g., `update.rs`).
|
||
|
|
* `feed.rs`: Logic for generating the Atom feed.
|
||
|
|
* `message.rs`: Defines structures for email messages.
|
||
|
|
* `message_reader/`: Contains logic for reading messages (e.g., `imap.rs` for IMAP fetching).
|
||
|
|
* `resources/`: Contains static resources like `feed.xsl` (for styling the feed) and `index.html` (for the output directory).
|
||
|
|
* `systemd/`: Contains systemd service and timer files for automated operation.
|
||
|
|
* `CHANGELOG.md`: Documents all notable changes.
|
||
|
|
* `README.md`: General project information and usage instructions.
|
||
|
|
|
||
|
|
|
||
|
|
For details on interacting with the Gitea API (issues, pull requests, etc.), refer to [.agents/gitea_api.md](.agents/gitea_api.md).
|