mxctl 0.3.0__tar.gz

mxctl-0.3.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: Bug Report
+about: Report a bug or unexpected behavior
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Bug Description
+<!-- A clear description of what the bug is -->
+
+## Steps to Reproduce
+1. Run command: `mxctl ...`
+2. See error: ...
+3. ...
+
+## Expected Behavior
+<!-- What you expected to happen -->
+
+## Actual Behavior
+<!-- What actually happened -->
+
+## Environment
+- macOS version:
+- Python version: (`python3 --version`)
+- mxctl version:
+- Mail.app version:
+
+## Error Messages
+```
+<!-- Paste any error messages or stack traces here -->
+```
+
+## Additional Context
+<!-- Any other relevant information -->

mxctl-0.3.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,25 @@
+---
+name: Feature Request
+about: Suggest a new feature or enhancement
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+---
+
+## Feature Description
+<!-- Clear description of the feature you'd like to see -->
+
+## Why is this useful?
+<!-- Explain the use case and who would benefit -->
+
+## Example Usage
+<!-- Show how you envision using this feature -->
+```bash
+mxctl ...
+```
+
+## Alternatives Considered
+<!-- Are there workarounds or alternative approaches? -->
+
+## Additional Context
+<!-- Any other relevant information, mockups, or examples -->

mxctl-0.3.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## What does this PR do?
+
+<!-- Brief description of the change -->
+
+## Why is this needed?
+
+<!-- What problem does it solve? Link to related issue if applicable -->
+
+## How was this tested?
+
+- [ ] Existing tests pass (`pytest`)
+- [ ] New tests added (if applicable)
+- [ ] Manually tested on macOS with Apple Mail
+
+## Checklist
+
+- [ ] Code follows existing patterns in the codebase
+- [ ] No external runtime dependencies added
+- [ ] Documentation updated (if user-facing change)

mxctl-0.3.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

mxctl-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check src/ tests/
+
+  test:
+    runs-on: macos-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest --cov --cov-report=term-missing

mxctl-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
+
+      - name: Extract changelog for this version
+        id: changelog
+        run: |
+          # Extract the section for this version from CHANGELOG.md
+          version="${GITHUB_REF#refs/tags/v}"
+          awk "/^## \\[${version}\\]/{found=1; next} /^## \\[/{if(found) exit} found{print}" CHANGELOG.md > /tmp/release-notes.md
+          echo "Release notes:"
+          cat /tmp/release-notes.md
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: ${{ steps.version.outputs.version }}
+          body_path: /tmp/release-notes.md
+          draft: false
+          prerelease: ${{ contains(github.ref, 'rc') || contains(github.ref, 'beta') }}

mxctl-0.3.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+
+# Config files (may contain tokens/personal data)
+config.json
+state.json
+mail-templates.json
+mail-undo.json
+
+# macOS
+.DS_Store
+**/.DS_Store
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Launch materials (not for public repo)
+REDDIT_LAUNCH.md
+
+# Local development instructions (personal, not for public repo)
+CLAUDE.md
+
+# Demo build artifacts (GIFs are committed, scripts are not)
+demo/*.cast
+demo/*.sh
+demo/bin/
+.coverage
+
+# Lock files
+uv.lock

mxctl-0.3.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.7
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

mxctl-0.3.0/ARCHITECTURE.md

@@ -0,0 +1,90 @@
+# Architecture
+
+This document explains the high-level design of mxctl for contributors.
+
+## Overview
+
+mxctl is a Python CLI that controls Apple Mail via AppleScript. It uses zero external runtime dependencies -- everything is built on Python's standard library.
+
+```
+User -> CLI (argparse) -> Command Module -> AppleScript Bridge -> Mail.app
+```
+
+## Directory Structure
+
+```
+src/mxctl/
+├── main.py                        # Top-level argparse router
+├── config.py                      # Constants, account resolution, validation
+├── util/
+│   ├── applescript.py             # run(), escape(), sanitize_path()
+│   ├── applescript_templates.py   # Reusable AppleScript patterns
+│   ├── formatting.py             # format_output(), truncate(), die()
+│   ├── mail_helpers.py           # resolve_message_context(), normalize_subject()
+│   └── dates.py                  # parse_date(), to_applescript_date()
+└── commands/
+    └── mail/
+        ├── __init__.py                # Package marker
+        ├── accounts.py                # inbox, accounts, mailboxes
+        ├── messages.py                # list, read, search
+        ├── actions.py                 # mark-read, mark-unread, flag, unflag, move, delete
+        ├── compose.py                 # draft (supports --template)
+        ├── attachments.py             # attachments, save-attachment
+        ├── manage.py                  # create-mailbox, delete-mailbox, empty-trash
+        ├── batch.py                   # batch-read, batch-flag, batch-move, batch-delete
+        ├── analytics.py               # stats, top-senders, digest, show-flagged
+        ├── setup.py                   # init (first-time setup wizard)
+        ├── system.py                  # check, headers, rules, junk, not-junk
+        ├── composite.py               # export, thread, reply, forward
+        ├── ai.py                      # summary, triage, context, find-related
+        ├── templates.py               # templates list/create/show/delete
+        ├── todoist_integration.py     # to-todoist
+        ├── inbox_tools.py             # process-inbox, clean-newsletters, weekly-review
+        └── undo.py                    # undo, undo --list
+```
+
+## AppleScript Bridge
+
+All Mail.app interaction goes through `util/applescript.py`, which wraps `osascript -e`. This module provides:
+
+- **`run(script, timeout=30)`** -- Execute an AppleScript string and return stdout
+- **`escape(string)`** -- Sanitize strings for safe embedding in AppleScript
+- **`sanitize_path(path)`** -- Expand and resolve file paths
+
+AppleScript returns multi-field data using `FIELD_SEPARATOR` (ASCII Unit Separator `\x1f`) and `RECORD_SEPARATOR` (ASCII Record Separator `\x1e`), defined in `config.py`. Command modules split on these to parse structured responses from Mail.app.
+
+Reusable AppleScript patterns (inbox iteration, message lookup) live in `applescript_templates.py` to avoid duplication across commands.
+
+## Three-Tier Account Resolution
+
+When a command needs a mail account, resolution follows this priority:
+
+1. **Explicit flag** -- `-a "Account Name"` on the command line
+2. **Config default** -- `default_account` in `~/.config/mxctl/config.json`
+3. **Last-used** -- Most recently used account stored in `state.json`
+
+This is implemented in `config.py:resolve_account()` and used by `util/mail_helpers.py:resolve_message_context()`.
+
+## Command Registration
+
+Each command module in `commands/mail/` exports a `register(subparsers)` function that adds its commands to the argparse tree. `main.py` imports and calls all `register()` functions directly.
+
+To add a new command:
+
+1. Add a handler function in the appropriate module (or create a new one)
+2. Add argparse registration in that module's `register()` function
+3. The router picks it up automatically
+
+## Output Convention
+
+Every command supports `--json` for structured output. The `format_output(args, text, json_data=...)` function in `util/formatting.py` handles routing -- it checks `args.json` and outputs either human-readable text or JSON accordingly.
+
+## Batch Operations & Undo
+
+Batch commands (`batch-read`, `batch-move`, `batch-delete`, `batch-flag`) log their operations to `mail-undo.json`. The `undo` command reads this log to reverse the most recent batch operation. Up to 10 operations are retained.
+
+## Testing
+
+Tests live in `tests/` and use `unittest.mock` to mock AppleScript calls. No actual Mail.app interaction happens during testing. Run with `pytest`.
+
+The suite has 348 tests across 17 test files covering command parsing, AppleScript output parsing, error paths, date handling, formatting, config resolution, batch operations, undo logging, templates, AI classification logic, unsubscribe HTTP paths, Todoist integration, inbox tools, and bulk export.

mxctl-0.3.0/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-02-24
+
+### Changed
+
+- **Renamed project** — `my-apple-mail-cli` is now `mxctl` ("mail control")
+- **Flattened CLI** — `my mail inbox` is now `mxctl inbox` (removed `mail` subcommand layer)
+- **Config path** — moved from `~/.config/my/` to `~/.config/mxctl/` with automatic one-time migration
+- **Version bump** — 0.2.0 → 0.3.0 (breaking: new binary name and command structure)
+- **Package name** — Python package renamed from `my_cli` to `mxctl`
+- **GitHub repo** — `Jscoats/my-apple-mail-cli` → `Jscoats/mxctl`
+- Test suite expanded to 422 tests
+
+## [0.2.0] - 2026-02-22
+
+### Added
+
+- `top-senders` command — rank senders by frequency with `--limit N`, `--json`, and optional mailbox filter
+- `batch-delete --from-sender EMAIL` flag — delete by sender across all mailboxes, combinable with `--older-than`
+- `NOREPLY_PATTERNS` centralized in `config.py` — single source of truth used by `triage`, `process-inbox`, `clean-newsletters`, and `weekly-review`
+- `TEMPLATES_FILE` path centralized in `config.py` — imported by `templates.py` and `compose.py`
+- File locking (`_file_lock`) applied to all JSON state reads and writes — `config.json`, `state.json`, `mail-undo.json`, `mail-templates.json`
+- 30 new tests covering templates CRUD, draft error paths, and batch dry-run edge cases (196 total)
+
+### Fixed
+
+- **Silent output failures** — three `cmd_mailboxes`, `_list_rules`, and `weekly-review` AppleScript strings were plain strings instead of f-strings; `FIELD_SEPARATOR` was passed as literal text causing commands to silently return empty results
+- `batch-delete` indexed iteration bug — list shifts after each delete causing skips and crashes
+- `batch-delete` Gmail All Mail error — individual deletions wrapped in `try/end try` so one IMAP failure doesn't abort the whole batch
+- `batch-delete` message IDs now logged only after a successful delete (previously logged before, so failed deletions appeared in the undo log)
+- `batch-move` — no error resilience; inner loop now wrapped in `try/end try` matching `batch-delete` pattern
+- `batch-move` — `--limit` only exited inner loop, allowing more messages to be processed than requested; outer loop now also checks limit
+- `batch-move` and `batch-delete` — dry-run reported total matching count instead of effective count when `--limit` is set
+- `cmd_not_junk` — hardcoded `"Junk"` mailbox name broke on Gmail accounts; now uses `resolve_mailbox()` for `[Gmail]/Spam` translation
+- `cmd_move` — source and destination mailbox names not translated for Gmail accounts; `resolve_mailbox()` now applied to both
+- `triage`, `process-inbox`, `clean-newsletters`, `weekly-review` — noreply pattern matching ran against full sender string including display name; now uses `extract_email()` to match against email address only
+- `compose.py` — template file read in `cmd_draft` had no JSON error handling; corrupt file now produces a friendly error
+- `compose.py` — template file read now uses `_file_lock` (previously read outside locking protocol)
+- `_file_lock` — file handle leaked on each failed retry attempt; fixed with `with open(...)` context manager
+- `setup.py` `cmd_init` — config written with bare `open()` bypassing `_file_lock`; now uses `_save_json()`
+- `_load_json` — reads were not locked (writes were); now symmetric
+- `list` command now accepts `-m`/`--mailbox` flag (was positional-only, inconsistent with all other commands)
+- `inbox` and `triage` now accept `-a` / `--account` to scope results to a single account
+- Gmail mailbox name mapping — `init` now asks which accounts are Gmail; `Spam`, `Trash`, `Sent`, `Archive` etc. auto-translate to `[Gmail]/...` equivalents
+- `accounts --json` returning empty `[]` instead of account data
+- `die()` return type corrected to `NoReturn`
+- Raw `\x1F`/`\x1FEND\x1F` literals in AppleScript strings replaced with `FIELD_SEPARATOR`/`RECORD_SEPARATOR` constants throughout
+- Removed dead code: unused `_convert_dates`, `account_iterator`, `single_message_lookup` functions; unused variable assignments in `todoist_integration.py` and `system.py`
+
+## [0.1.0] - 2026-02-21
+
+### Added
+
+- **First-run setup** — `init` wizard for account detection and optional Todoist token configuration
+- **Account management** — `inbox`, `accounts`, `mailboxes`, `create-mailbox`, `delete-mailbox`, `empty-trash`, `count` for scripting and status bars
+- **Message operations** — `list`, `read`, `search`, `mark-read`, `mark-unread`, `flag`, `unflag`, `move`, `delete`, `open` for GUI access
+- **AI-powered features** — `summary`, `triage`, `context`, `find-related`, `process-inbox`
+- **Batch operations with undo** — `batch-read`, `batch-flag`, `batch-move`, `batch-delete`, `undo`
+- **Analytics** — `stats`, `digest`, `show-flagged`, `weekly-review`, `clean-newsletters`
+- **Compose & templates** — `draft` with template support, `reply`, `forward`, `templates` subcommands
+- **Integrations** — `to-todoist` for sending emails as Todoist tasks, `export` for Mbox format
+- **System tools** — `check`, `headers`, `rules`, `junk`, `not-junk`
+- Multi-account support with three-tier account resolution
+- `--json` output mode on every command
+- Comprehensive test suite (166 tests)
+- Zero runtime dependencies (Python stdlib only)

mxctl-0.3.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,39 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by opening an issue or contacting the project maintainer. All
+complaints will be reviewed and investigated and will result in a response
+that is deemed necessary and appropriate to the circumstances.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).

mxctl-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,144 @@
+# Contributing to mxctl
+
+Thanks for your interest in contributing!
+
+This project welcomes contributions from the community. Whether you're fixing a bug, adding a feature, or improving documentation, your help is appreciated.
+
+## Reporting Bugs
+
+Found a bug? Please [open an issue](https://github.com/Jscoats/mxctl/issues/new?template=bug_report.md) with:
+
+- Clear description of the problem
+- Steps to reproduce
+- Expected vs actual behavior
+- Your environment (macOS version, Python version, Mail.app version)
+- Relevant error messages or logs
+
+**Note:** Please check existing issues first to avoid duplicates.
+
+## Requesting Features
+
+Have an idea? [Open a feature request](https://github.com/Jscoats/mxctl/issues/new?template=feature_request.md) with:
+
+- Clear description of the feature
+- Why it would be useful
+- Example usage (if applicable)
+
+## Contributing Code
+
+### Prerequisites
+
+> **macOS required.** This tool uses AppleScript to control Mail.app, which is macOS-only. Contributors on Linux or Windows cannot run or test the tool. All development and testing must be done on macOS.
+
+- macOS 12 or later
+- Python 3.10+
+- Mail.app with at least one configured account
+- [`uv`](https://docs.astral.sh/uv/) (recommended) or `pip`
+
+### Before You Start
+
+1. **Check existing issues** - Someone might already be working on it
+2. **Discuss major changes** - Open an issue first for big features/refactors
+3. **Keep it focused** - One feature/fix per pull request
+
+### Development Setup
+
+```bash
+# Clone the repo
+git clone https://github.com/Jscoats/mxctl.git
+cd mxctl
+
+# Install in editable mode (primary -- uses uv)
+uv tool install -e .          # Install
+uv tool install -e . --force  # Reinstall after changes
+
+# Run tests
+pytest
+```
+
+**Fallback:** If you are not using `uv`, you can install with pip instead:
+```bash
+pip install -e ".[dev]"
+```
+
+### Code Guidelines
+
+**Follow existing patterns:**
+- Match the style of surrounding code
+- Use existing utilities in `src/mxctl/util/`
+- Add AppleScript code to `applescript_templates.py` if reusable
+- Keep functions focused and testable
+
+**Zero runtime dependencies:**
+- This project uses only Python stdlib
+- Do not add external packages without discussion
+
+**Testing:**
+- Add tests for new features
+- Ensure existing tests pass: `pytest`
+- Test files live in `tests/`
+- Mock AppleScript calls in tests (see existing test files for examples)
+
+**Documentation:**
+- Update README.md if adding user-facing features
+- Add docstrings to new functions
+- Update ARCHITECTURE.md for architectural changes
+
+### Pull Request Process
+
+1. **Fork the repo** and create a feature branch
+   ```bash
+   git checkout -b feature/my-new-feature
+   ```
+
+2. **Make your changes**
+   - Write clean, readable code
+   - Add tests for new functionality
+   - Update documentation
+
+3. **Test thoroughly**
+   ```bash
+   pytest  # All tests must pass
+   ```
+
+4. **Commit with clear messages**
+   ```bash
+   git commit -m "Add email filter by date range"
+   ```
+
+5. **Push and create a pull request**
+   ```bash
+   git push origin feature/my-new-feature
+   ```
+
+6. **Describe your changes** in the PR:
+   - What does it do?
+   - Why is it needed?
+   - How was it tested?
+
+### Code Review
+
+- PRs will be reviewed for code quality, test coverage, and alignment with project goals
+- Be patient - reviews may take a few days
+- Be open to feedback and iteration
+
+## Documentation
+
+Documentation improvements are always welcome! You can help by:
+
+- Fixing typos or unclear wording
+- Adding examples to the README
+- Improving code comments
+- Writing tutorials or guides
+
+## Questions?
+
+Not sure about something? Open an issue with the `question` label or reach out via GitHub discussions.
+
+## Thank You!
+
+Every contribution, no matter how small, helps make this project better. Thank you for being part of the community!
+
+---
+
+**By contributing, you agree that your contributions will be licensed under the project's MIT License.**

mxctl-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jscoats
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.