newsletter-to-web/AGENTS.md at master

Files

JJKiers Agent 81fc63474f docs: Introduce comprehensive agent guidance and Gitea API documentation

This commit adds new documentation to enhance agent readiness within the repository:

- `AGENTS.md`: Provides a high-level overview of the project's purpose, technical stack, key workflows, and repository structure.
- `.agents/gitea_api.md`: Contains detailed instructions and examples for programmatic interaction with the Gitea API, covering operations like fetching and creating issues/pull requests, along with a quick reference of API capabilities.

These additions aim to streamline future autonomous operations by centralizing essential repository knowledge and API usage guidelines. It replaces previous ad-hoc methods for interacting with Gitea.

2026-02-14 19:16:07 +00:00

2.7 KiB

Raw Permalink Blame History

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.

2.7 KiB Raw Permalink Blame History

AGENTS.md for newsletter-to-web