From 25e59d50ca7ba30e35297cedf65f6a37f9339515 Mon Sep 17 00:00:00 2001 From: Drew Smirnoff Date: Wed, 18 Mar 2026 14:39:52 +0400 Subject: [PATCH] docs: add README in each folder (#327) --- config/README.md | 24 +++++++++++++++++++ docs/README.md | 56 +++++++++++++++++++++++++++++++++++++++++++ fetcher/README.md | 15 ++++++++++++ public/README.md | 30 +++++++++++++++++++++++ screenshots/README.md | 23 ++++++++++++++++++ sender/README.md | 13 ++++++++++ theme/README.md | 12 ++++++++++ tui/README.md | 41 +++++++++++++++++++++++++++++++ view/README.md | 16 +++++++++++++ 9 files changed, 230 insertions(+) create mode 100644 config/README.md create mode 100644 docs/README.md create mode 100644 fetcher/README.md create mode 100644 public/README.md create mode 100644 screenshots/README.md create mode 100644 sender/README.md create mode 100644 theme/README.md create mode 100644 tui/README.md create mode 100644 view/README.md diff --git a/config/README.md b/config/README.md new file mode 100644 index 0000000000000000000000000000000000000000..7189dd3c83664121e342d2c4642639bc9c1c05c8 --- /dev/null +++ b/config/README.md @@ -0,0 +1,24 @@ +# config + +The `config` package handles all persistent application state: user configuration, email/contacts/drafts caching, folder caching, and email signatures. All data is stored as JSON files under `~/.config/matcha/`. + +## Architecture + +This package acts as the data layer for Matcha. It manages: + +- **Account configuration** with multi-account support (Gmail, iCloud, custom IMAP/SMTP) +- **Secure credential storage** via the OS keyring (with automatic migration from plain-text passwords) +- **Local caches** for emails, contacts, drafts, and folder listings to enable fast startup and offline browsing +- **Email signatures** stored as plain text + +All cache files use JSON serialization with restrictive file permissions (`0600`/`0700`). + +## Files + +| File | Description | +|------|-------------| +| `config.go` | Core configuration types (`Account`, `Config`, `MailingList`) and functions for loading, saving, and managing accounts. Handles IMAP/SMTP server resolution per provider, OS keyring integration, and legacy config migration. | +| `cache.go` | Email, contacts, and drafts caching. Provides CRUD operations for `EmailCache`, `ContactsCache` (with search and frequency-based ranking), and `DraftsCache` (with save/delete/get operations). | +| `folder_cache.go` | Caches IMAP folder listings per account and per-folder email metadata. Stores folder names to avoid repeated IMAP `LIST` commands, and caches email headers per folder for fast navigation. | +| `signature.go` | Loads and saves the user's email signature from `~/.config/matcha/signature.txt`. | +| `config_test.go` | Unit tests for configuration logic. | diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000000000000000000000000000000000..687b678b2b9caa0547838b519ceeb85055fd4152 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,56 @@ +# docs + +Documentation website built with [Docusaurus](https://docusaurus.io/). Contains user-facing guides, feature documentation, and a blog. + +## Architecture + +A Docusaurus 3 project that generates a static documentation site. The content is organized into guides (installation, usage, configuration) and feature-specific pages. + +## Files + +| File | Description | +|------|-------------| +| `docusaurus.config.ts` | Main Docusaurus configuration (site metadata, theme, plugins). | +| `sidebars.ts` | Documentation sidebar navigation structure. | +| `package.json` | Node.js dependencies for building the docs site. | +| `tsconfig.json` | TypeScript configuration. | + +### docs/ + +Documentation content pages: + +| File | Description | +|------|-------------| +| `index.md` | Documentation home page. | +| `installation.md` | Installation guide for all platforms. | +| `usage.md` | Usage guide and keyboard shortcuts. | +| `Configuration.md` | Configuration file reference. | + +### docs/Features/ + +Feature-specific documentation: + +| File | Description | +|------|-------------| +| `ACCOUNTS.md` | Multi-account setup and management. | +| `ADVANCED.md` | Advanced features (S/MIME, custom servers). | +| `COMPOSING.md` | Email composition guide. | +| `CONTACTS.md` | Contact management and autocomplete. | +| `DRAFTS.md` | Draft saving and restoration. | +| `EMAIL_MANAGEMENT.md` | Email actions (delete, archive, move). | +| `Hyperlinks.md` | Terminal hyperlink support. | +| `Images.md` | Inline image rendering and protocols. | +| `Themes.md` | Theme customization and custom themes. | +| `UI.md` | General UI documentation. | + +### docs/assets/ + +Screenshot images used in the documentation pages. + +### src/ + +Custom React components and CSS for the documentation site theme. + +### static/ + +Static assets (logos, images) served directly by the documentation site. diff --git a/fetcher/README.md b/fetcher/README.md new file mode 100644 index 0000000000000000000000000000000000000000..a2a584c9d2dd4126af6bc49d90c225be0dd2614d --- /dev/null +++ b/fetcher/README.md @@ -0,0 +1,15 @@ +# fetcher + +The `fetcher` package handles all email retrieval operations over IMAP. It connects to mail servers, fetches email headers and bodies, manages attachments, and supports mailbox operations like delete, archive, and move. + +## Architecture + +This package is the IMAP client layer for Matcha. It: + +- Establishes TLS/STARTTLS connections to IMAP servers based on account configuration +- Fetches email lists with pagination and per-account filtering (using `FetchEmail` to match relevant messages) +- Retrieves full email bodies with MIME part traversal (preferring HTML over plain text) +- Handles attachments including inline images (with CID references) and file attachments +- Supports S/MIME decryption (opaque and enveloped) and detached signature verification +- Provides mailbox operations: delete (expunge), archive (move), and folder-to-folder moves +- Exposes both mailbox-specific and convenience functions (e.g., `FetchEmails` defaults to INBOX) diff --git a/public/README.md b/public/README.md new file mode 100644 index 0000000000000000000000000000000000000000..dd164c5ba071c26ebb7ed3215ee59452f5d634f5 --- /dev/null +++ b/public/README.md @@ -0,0 +1,30 @@ +# public + +Static website files for the Matcha project landing page. This site is deployed via GitHub Pages using the `.github/workflows/static.yml` workflow. + +## Architecture + +A simple static HTML/CSS website that serves as the public-facing project page with information about features, installation, and contact details. + +## Files + +| File | Description | +|------|-------------| +| `index.html` | Main landing page. | +| `style.css` | Stylesheet for all pages. | +| `matcha.flatpakref` | Flatpak package reference for Linux distribution. | +| `features/index.html` | Features overview page. | +| `get-started/index.html` | Getting started / installation guide page. | +| `contact/index.html` | Contact information page. | + +### assets/ + +| File | Description | +|------|-------------| +| `demo.gif` | Animated terminal demo. | +| `logo.png` | Project logo. | +| `logo-transparent.png` | Logo with transparent background. | +| `logo.txt` | ASCII text version of the logo. | +| `favicon.ico` | Browser favicon. | +| `preview.png` | Social media / link preview image. | +| `screenshots/` | Directory for generated UI screenshots (populated by CI). | diff --git a/screenshots/README.md b/screenshots/README.md new file mode 100644 index 0000000000000000000000000000000000000000..87c313c94e9c66f69b8fd3889af9203af05295be --- /dev/null +++ b/screenshots/README.md @@ -0,0 +1,23 @@ +# screenshots + +This directory contains tooling for automated terminal UI screenshot generation using [VHS](https://github.com/charmbracelet/vhs), a terminal recording and screenshot tool. + +## Architecture + +Screenshots are generated through a two-layer system: + +1. **Go helper programs** (`cmd/`) that render realistic mock UI views using real Matcha components with fake data +2. **VHS tape scripts** (`.tape` files) that launch these programs and capture terminal output as images + +This pipeline runs in CI via the `.github/workflows/screenshots.yml` workflow to keep documentation screenshots up-to-date automatically. + +## Files + +### Helper Programs + +| File | Description | +|------|-------------| +| `cmd/inbox_view/main.go` | Renders a mock inbox populated with realistic email entries for screenshot capture. | +| `cmd/email_view/main.go` | Renders a mock email view with headers, body content, and inline images for screenshot capture. | + +The rest are the tapes themselves diff --git a/sender/README.md b/sender/README.md new file mode 100644 index 0000000000000000000000000000000000000000..07cae9fcc2cdc6790bc1fe9754008a5909120321 --- /dev/null +++ b/sender/README.md @@ -0,0 +1,13 @@ +# sender + +The `sender` package handles email composition and delivery over SMTP. It constructs properly formatted multipart MIME messages and sends them through the configured SMTP server. + +## Architecture + +This package is the SMTP client layer for Matcha. It: + +- Builds multipart MIME messages with plain text, HTML, inline images, and file attachments +- Supports S/MIME detached signing and envelope encryption using PKCS#7 +- Handles SMTP authentication with both PLAIN and LOGIN mechanisms (fallback for servers like Mailo) +- Supports both implicit TLS (port 465) and STARTTLS (other ports) +- Generates unique Message-IDs and handles reply threading via `In-Reply-To` and `References` headers diff --git a/theme/README.md b/theme/README.md new file mode 100644 index 0000000000000000000000000000000000000000..5ab427ec94dd19f9f55c251ee8e728104acdf1d2 --- /dev/null +++ b/theme/README.md @@ -0,0 +1,12 @@ +# theme + +The `theme` package defines the color palette system for Matcha's terminal UI. It provides built-in themes and supports user-created custom themes. + +## Architecture + +Each theme is a set of named colors (accent, danger, warning, link, etc.) used consistently across all UI components. The package: + +- Defines 6 built-in themes: Matcha, Rose, Lavender, Ocean, Peach, and Catppuccin Mocha +- Supports custom themes loaded from `~/.config/matcha/themes/*.json` +- Maintains a global `ActiveTheme` variable that all UI components reference +- Uses Lip Gloss color values for terminal-compatible color rendering diff --git a/tui/README.md b/tui/README.md new file mode 100644 index 0000000000000000000000000000000000000000..f7a6704f2b9a5909e00b604d0e93662fc0a945a4 --- /dev/null +++ b/tui/README.md @@ -0,0 +1,41 @@ +# tui + +The `tui` package contains all terminal user interface components built with the [Bubble Tea](https://github.com/charmbracelet/bubbletea) framework. Each file implements a self-contained view or component following the Bubble Tea Model-View-Update (MVU) pattern. + +## Architecture + +The TUI layer is the interactive frontend of Matcha. Each view implements the `tea.Model` interface (`Init`, `Update`, `View`) and communicates with other views through typed messages. The main application (`main.go`) orchestrates navigation between views by swapping the active model. + +### Views + +| File | Description | +|------|-------------| +| `inbox.go` | Email inbox list with multi-account tab support. Handles pagination, keyboard navigation, and renders email items with sender, subject, and date. Supports different mailbox types (inbox, sent, trash, archive) and both multi-account and single-account modes. | +| `email_view.go` | Full email display in a scrollable viewport. Shows headers (from, to, subject, date), rendered body content, attachment list, and S/MIME verification status. Manages inline image rendering through out-of-band stdout writes. | +| `composer.go` | Email composition form with fields for To, CC, BCC, Subject, and Body. Features contact autocomplete, file attachment picker, signature insertion, account selection dropdown, and draft auto-saving. Supports reply mode with pre-filled headers and quoted text. | +| `drafts.go` | Draft email list view. Displays saved drafts with subject, recipient, and timestamp. Allows opening drafts in the composer or deleting them. | +| `folder_inbox.go` | Folder navigation sidebar with an email list. Displays IMAP folders in a left panel and the selected folder's emails in the main area. Handles folder selection and email loading per folder. | +| `trash_archive.go` | Combined trash and archive view with tab-based switching between the two. Shares the inbox component structure but targets trash/archive mailboxes. | +| `login.go` | Account login form supporting Gmail, iCloud, and custom IMAP/SMTP providers. Collects credentials, server settings, and optionally S/MIME certificate paths. Validates input before submission. | +| `settings.go` | Settings panel for managing accounts (add/remove), configuring mailing lists, editing signatures, toggling image display, managing tips visibility, and setting up S/MIME certificates. | +| `mailing_list.go` | Editor for creating and modifying mailing list groups (name + comma-separated email addresses). | +| `choice.go` | Main menu / start screen. Presents account selection, navigation to inbox, compose, drafts, sent, folders, trash/archive, and settings. | +| `filepicker.go` | File browser for selecting email attachments. Navigates the filesystem with directory listing and file selection. | + +### Supporting Files + +| File | Description | +|------|-------------| +| `styles.go` | Global Lip Gloss style definitions used across all views (dialog boxes, help text, tips, headings, body text). Also defines the `Status` component for spinner-based loading messages. | +| `theme.go` | `RebuildStyles` function that updates all package-level style variables when the active theme changes, ensuring consistent colors across the UI. | +| `messages.go` | Shared message types for inter-component communication: `ViewEmailMsg`, `SendEmailMsg`, `Credentials`, `ChooseServiceMsg`, `EmailResultMsg`, `ClearStatusMsg`, and the `MailboxKind` enum. | +| `signature.go` | Textarea-based editor for composing and saving email signatures. | + +### Test Files + +| File | Description | +|------|-------------| +| `inbox_test.go` | Tests for inbox rendering and behavior. | +| `email_view_test.go` | Tests for email view rendering. | +| `composer_test.go` | Tests for email composition logic. | +| `trash_archive_test.go` | Tests for trash/archive view behavior. | diff --git a/view/README.md b/view/README.md new file mode 100644 index 0000000000000000000000000000000000000000..a80021cc717cdf2d0c8e65377e790e937451f3d2 --- /dev/null +++ b/view/README.md @@ -0,0 +1,16 @@ +# view + +The `view` package handles rendering email content for terminal display. It converts HTML email bodies into styled terminal text with support for inline images, hyperlinks, and quoted reply formatting. + +## Architecture + +This package bridges raw email content (HTML/Markdown) and terminal output. It: + +- Parses HTML email bodies using goquery and converts them to styled terminal text +- Renders hyperlinks using OSC 8 escape sequences (with fallback for unsupported terminals) +- Supports inline image rendering via multiple terminal graphics protocols: + - **Kitty Graphics Protocol** (Kitty, Ghostty, WezTerm, Wayst, Konsole) + - **iTerm2 Image Protocol** (iTerm2, Warp) +- Detects quoted reply sections (`>` prefixed lines and `On DATE, EMAIL wrote:` patterns) and renders them in styled quote boxes +- Manages image lifecycle: fetching remote images, resolving CID references, caching, uploading to terminal memory (Kitty IDs), and calculating terminal row placement +- Converts Markdown to HTML via Goldmark before processing