From 16c054b09ab3746bd3095c12a10c3d725b61b118 Mon Sep 17 00:00:00 2001 From: Exe Zulliger Date: Wed, 8 Jul 2026 23:27:45 +0200 Subject: [PATCH] docs: clean up AGENTS.md and append session log AGENTS.md: - Add 'Install for agents' section (install-skill, release assets, per-platform download) - Add lib.rs, search.rs, and tests/ to project tree - Replace stale 'No history yet' / 'Integration (planned)' lines with current state - Frame the file as designed for both humans and AI coding agents memory.md: append v0.1.0 release notes + this session's gh-CLI-sandbox workaround Co-authored-by: PeakBot! --- AGENTS.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++---- memory.md | 35 ++++++++++++++++++++++ 2 files changed, 116 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d630c5a..e8ed35e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,17 +2,24 @@ `mail-cli` is a single-binary, **stateless** IMAP/SMTP email client in Rust. Config comes **only** from `MAILCLI_*` environment variables; everything else is -a CLI flag. No config file, no cache, no stored state. Read [`PLAN.md`](PLAN.md) -before non-trivial work — it is the locked source of truth. +a CLI flag. No config file, no cache, no stored state. + +This file and this repo are designed for **both humans and AI coding agents**. +Agents are first-class: the `skill/` directory ships an agent-facing usage +skill (`SKILL.md` + references + evals) that is **embedded into the binary** +and materialized by `mail-cli install-skill` — see +[Install for agents](#install-for-agents) below. ## Project Structure & Module Organization ``` src/ main.rs // clap surface, Selector enum, live selector resolution, dispatch + lib.rs // library facade; re-exports only `search` (pure) for integration tests config.rs // the ONLY boundary that reads env; per-command validation imap.rs // the ONLY place that talks IMAP (connect/auth/list/fetch) parse.rs // mail-parser wrappers; Summary/Rendered/Attachment structs + search.rs // Criteria -> server-side IMAP SEARCH query builder (pure, offline-testable) smtp.rs // lettre message build (+attachments) and send skill.rs // embeds skill/ assets; install-skill writes them to disk output.rs // human tables + --json serialization @@ -20,10 +27,75 @@ src/ skill/ // the bundled agent skill (SKILL.md + references/ + evals/), // embedded into the binary via include_str! and materialized by // `mail-cli install-skill`. Keep in sync with the shipped skill. + +tests/ // integration tests, gated on MAILCLI_IT=1 (GreenMail) ``` Structs live with the module that owns them (no `model.rs`). Keep IMAP calls -inside `imap.rs` so a future async swap stays contained. +inside `imap.rs` so a future async swap stays contained. `search.rs` is pure +on purpose so the query builder stays unit-testable without a server. + +## Install for agents + +The `install-skill` subcommand reads **no** `MAILCLI_*` env vars — it is purely +local — so it's safe to run before any account config exists. + +Prebuilt release assets live at +[`github.com/patch-notes/mail-cli/releases/latest`](https://github.com/patch-notes/mail-cli/releases/latest). +Naming: `mail-cli--[-amd64|-arm64][.exe]` +(e.g. `mail-cli-0.1.0-linux-amd64`, `mail-cli-0.1.0-macos-arm64.exe` — note +`.exe` only on Windows). + +Linux: + +```sh +# 1. Download the latest prebuilt binary for Linux amd64 +curl -L -o mail-cli \ + https://github.com/patch-notes/mail-cli/releases/latest/download/mail-cli-linux-amd64 +chmod +x mail-cli +``` + +macOS (Apple Silicon shown; swap `arm64` -> `amd64` for Intel): + +```sh +curl -L -o mail-cli \ + https://github.com/patch-notes/mail-cli/releases/latest/download/mail-cli-macos-arm64 +chmod +x mail-cli +xattr -d com.apple.quarantine mail-cli # gatekeeper, first run only +``` + +Windows (PowerShell): + +```powershell +Invoke-WebRequest -OutFile mail-cli.exe ` + https://github.com/patch-notes/mail-cli/releases/latest/download/mail-cli-windows-amd64.exe +``` + +Available asset names: `mail-cli-linux-amd64`, `mail-cli-macos-amd64`, +`mail-cli-macos-arm64`, `mail-cli-windows-amd64.exe`. Pin a version by replacing +`latest` with `v0.1.0` etc. + +Then, regardless of platform, materialize the skill: + +```sh +./mail-cli install-skill # or .\mail-cli.exe install-skill on Windows +# -> ~/.agents/skills/mail-cli/ (or %USERPROFILE%\.agents\skills\mail-cli) +``` + +`gh` users: +`gh release download -R patch-notes/mail-cli -p 'mail-cli-*linux-amd64*'`. +Source builders: `cargo build --release`, then +`./target/release/mail-cli install-skill`. + +Finally, optionally move the binary somewhere on `PATH`: + +```sh +sudo mv mail-cli /usr/local/bin/ # Linux/macOS — or anywhere on $PATH +``` + +After this, the `mail-cli` skill is on disk and the agent can run any +`mail-cli` command — but real mail access still requires the +`MAILCLI_*` env vars from [Security & Configuration](#security--configuration). ## Build, Test, and Development Commands @@ -32,6 +104,8 @@ inside `imap.rs` so a future async swap stays contained. - `cargo test` — run unit tests (in-module `#[cfg(test)]`). - `cargo clippy --all-targets` — lint; keep it **warning-free**. - `cargo run -- ` — e.g. `cargo run -- folders`. +- `MAILCLI_IT=1 cargo test --test search_integration` — GreenMail integration + (requires a running GreenMail server; see README). ## Coding Style & Naming Conventions @@ -46,13 +120,14 @@ inside `imap.rs` so a future async swap stays contained. - Unit tests sit beside code in `mod tests`. Cover parsing (inline `.eml` fixtures), `Selector` parsing, and `Config` env cases. - **Every bug fix starts with a failing test** that reproduces it, then the fix. -- Integration (planned): GreenMail in Docker for connect→list→fetch and send. +- Integration: `tests/search_integration.rs` (GreenMail) — gated on + `MAILCLI_IT=1` so plain `cargo test` stays offline. ## Commit & Pull Request Guidelines -- No history yet; use concise, imperative commits (e.g. `add search command`). +- Use concise, imperative commits (e.g. `add search command`). - One logical change per commit; keep diffs small and focused. -- PRs: describe intent, link plan section, note test coverage; ensure +- PRs: describe intent, note test coverage; ensure `cargo test` + `cargo clippy` are clean. ## Security & Configuration diff --git a/memory.md b/memory.md index ec5847f..6e61a37 100644 --- a/memory.md +++ b/memory.md @@ -121,3 +121,38 @@ ONLY env reader; per-command validation via ImapConfig/SmtpConfig::from_env. - Build: `cargo build` clean, `cargo test` 11 pass, `cargo clippy` clean. - STILL TODO (M4/v2): GreenMail Docker integration tests; real-provider smoke test. + +- 2026-07-08 (rev 9): FIRST GITHUB RELEASE v0.1.0. Repo=patch-notes/mail-cli + (GitHub). CI branch ci/add-github-actions was already merged to master via PR + #1 (commit 89a0b3a) — ci.yml + release.yml live on master. Verified local + fmt/clippy/test all green. Tagged annotated v0.1.0 on 89a0b3a (Cargo.toml + version=0.1.0 matches the release.yml guardrail) and pushed -> Release + workflow run 28973982166 (4-target matrix: linux-amd64, macos-arm64, + macos-amd64, windows-amd64; publish job uploads dist/* via + softprops/action-gh-release, generate_release_notes). + GOTCHA: `gh` CLI HANGS in this sandbox — it connects to GitHub (TLS OK per + strace) but the HTTP read never returns; every `gh api`/`gh pr` call times + out at 124. WORKAROUND: `gh auth token` (reads local config, fast, no net) + + drive git via authenticated URL + https://x-access-token:$TOK@github.com/... and drive the GitHub REST API via + curl -H "Authorization: token $TOK". Raw curl to api.github.com is fast + (~0.17s). Use this pattern for all GitHub ops here. + +- 2026-07-08 (rev 10): Cleaned up AGENTS.md. (a) REMOVED all references to + PLAN.md and the "No history yet; ..." hint — both stale (no PLAN.md on disk; + v0.1.0 release exists, so there IS history). (b) Added missing files to the + project tree: src/lib.rs (facade exposing only `search` for tests) and + src/search.rs (Criteria + to_imap_query, pure), and the tests/ directory + (search_integration.rs, gated on MAILCLI_IT=1). (c) Added a top-of-file + agent-first framing: "designed for both humans and AI coding agents" + the + skill/agent install path. (d) New "Install for agents" section: explains + install-skill reads NO MAILCLI_* env, lists the 4 release asset names + (mail-cli-linux-amd64, mail-cli-macos-amd64, mail-cli-macos-arm64, + mail-cli-windows-amd64.exe) with correct download URLs at + github.com/patch-notes/mail-cli/releases/latest/download/, gives + per-platform curl/Invoke-WebRequest commands, then `./mail-cli install-skill`. + NOTES: macOS needs `xattr -d com.apple.quarantine` first run; Windows is + PowerShell; `gh release download -R patch-notes/mail-cli -p '...'` for gh + users; `cargo build --release` then install-skill for source builders. + Re-verified release assets via `gh release view v0.1.0 --repo + patch-notes/mail-cli --json assets` (worked this time, ~0.5s).