From 81fc63474f3ac67887fb319347fe5b1cd7fe5bc4 Mon Sep 17 00:00:00 2001 From: JJKiers Agent Date: Sat, 14 Feb 2026 19:06:38 +0000 Subject: [PATCH] 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. --- .agents/gitea_api.md | 61 ++++++++++++++++++++++++++++++++++++++++++++ AGENTS.md | 56 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 117 insertions(+) create mode 100644 .agents/gitea_api.md create mode 100644 AGENTS.md diff --git a/.agents/gitea_api.md b/.agents/gitea_api.md new file mode 100644 index 0000000..9f772dd --- /dev/null +++ b/.agents/gitea_api.md @@ -0,0 +1,61 @@ +## Working with Gitea (API Guidance) + +### Gitea API Features (Quick Reference) + +The Gitea API provides extensive functionality for repository management, user interaction, and project oversight. Key features include: + +* **Repository Management**: Create, delete, edit repositories; manage branches, commits, and tags. +* **Issues & Pull Requests**: Create, view, update issues and pull requests; manage comments, labels, and milestones. +* **User Management**: Access user profiles, manage SSH keys, GPG keys, and email addresses. +* **Organization & Teams**: Interact with organizations and their associated teams. +* **Notifications**: Manage user notifications. +* **Activity Feeds**: Retrieve user and repository activity. +* **Webhooks**: Configure webhooks for repository events. + +For complete details and all available endpoints, refer to the [Gitea Swagger API Documentation](https://code.kiers.eu/swagger.v1.json). + +This repository is hosted on Gitea. Direct API calls are often required for tasks like fetching issues, creating pull requests, etc., as specific tools might not always be available. + +**Base URL:** `https://code.kiers.eu` +**API Endpoint Prefix:** `/api/v1` +**Repository Path:** `newsletter-to-web/newsletter-to-web` + +You can use `curl` with the `FORGEJO_TOKEN` (which serves as your Gitea token) for authentication. + +### Key API Interactions: + +1. **Fetch Issues:** + To get a list of all open issues for this repository: + ```bash + curl -H "Authorization: Bearer ${FORGEJO_TOKEN}" https://code.kiers.eu/api/v1/repos/newsletter-to-web/newsletter-to-web/issues + ``` + +2. **Fetch Pull Requests (Merge Requests):** + Gitea uses "pull requests" in its API, though the UI might call them "merge requests." + ```bash + curl -H "Authorization: Bearer ${FORGEJO_TOKEN}" https://code.kiers.eu/api/v1/repos/newsletter-to-web/newsletter-to-web/pulls + ``` + +3. **Create an Issue:** + You would typically `POST` to the issues endpoint. The `labels` field expects an array of label IDs. Example (replace with actual data): + ```bash + curl -X POST -H "Authorization: Bearer ${FORGEJO_TOKEN}" -H "Content-Type: application/json" -d '{ + "title": "New Issue Title", + "body": "Description of the new issue.", + "labels": [1, 2] # Use numerical label IDs + }' https://code.kiers.eu/api/v1/repos/newsletter-to-web/newsletter-to-web/issues + ``` + *Note: You would need to fetch available labels and their IDs first if you want to apply them.* + +4. **Create a Pull Request:** + You would typically `POST` to the pulls endpoint. Example (replace with actual data and branches): + ```bash + curl -X POST -H "Authorization: Bearer ${FORGEJO_TOKEN}" -H "Content-Type: application/json" -d '{ + "head": "your-branch-name", + "base": "main", + "title": "DRAFT: My New Pull Request", + "body": "Detailed description of changes in this PR." + }' https://code.kiers.eu/api/v1/repos/newsletter-to-web/newsletter-to-web/pulls + ``` + * `head`: The branch with your changes. + * `base`: The branch you want to merge into (e.g., `main`). diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c87781a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,56 @@ +# 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 -u -p ` + +### 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).