From f1890fc7b5fe1094445ce8b83c2d2f15258fceec Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Wed, 12 Aug 2026 11:42:14 +0200 Subject: feat(rules): read-only rules list and show Editing stays out of this tool: a rule edit affects every future sync and its gate is not designed yet. qtmaildir has the editor. The install step now copies mailrules.py beside mailctl.py. The import resolves from the script's own directory, so copying only mailctl.py would break every command, not just the new ones. --- CLAUDE.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) (limited to 'CLAUDE.md') diff --git a/CLAUDE.md b/CLAUDE.md index 24fdf21..db9ca07 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,7 +18,7 @@ simply nothing to sync with in this tree. No installer, just copy files into place: ```bash -cp mailctl.py ~/bin/ # executable (skill calls ~/bin/mailctl.py) +cp mailctl.py mailrules.py ~/bin/ # executable + module (skill calls ~/bin/mailctl.py) cp -r mail-organize ~/.claude/skills/ # skill in its own directory ``` @@ -36,6 +36,9 @@ The skill's `allowed-tools` expects the tool at `~/bin/mailctl.py`; keep that pa ./mailctl.py subjects QUERY [--account NAME] [--top N] # subject terms ranked by thread count ./mailctl.py tag QUERY --account NAME --add work --remove inbox # dry-run ./mailctl.py tag QUERY --account NAME --add work --apply # commit +./mailctl.py rules list [--enabled-only] # shared tagging rules, read-only +./mailctl.py rules show +./mailctl.py rules dry-run [] # what each rule matches now ``` Requires `notmuch` on PATH and a synced Maildir at `~/Mail`. No build, no deps beyond the stdlib and the `notmuch` binary. The only test is `./test_mailctl.py` (plain asserts, no framework), covering the `senders` address-merge and `subjects` term-counting logic. @@ -49,6 +52,12 @@ These invariants are the point of the tool. Preserve them when editing: - **Destructive changes need a second gate.** Adding a tag in `DESTRUCTIVE_TAGS` (`deleted`/`trash`/`spam`) or removing one in `PROTECTED_REMOVALS` (`inbox`) requires `--apply` AND `--confirm-destructive`. - **Bulk mutations are capped.** `tag --apply` aborts if the match count exceeds `--max-messages` (default `DEFAULT_MAX_MESSAGES`, 5000). Raise the flag to override for a deliberate large batch. - **Every applied mutation is audited** to `~/.local/state/mailctl/audit.log` (tab-separated, timestamped) via `log_mutation`. +- **Rules are read-only from this tool.** `mailctl rules` lists, shows and + dry-runs the shared store at `~/.config/mailrules/rules.json`, and cannot + edit it. A rule edit is a mutation whose blast radius is every future sync, + and the gate for that is not designed yet; qtmaildir has the editor. + `mailrules.save()` exists because the format's write semantics must be + shared, but no CLI surface reaches it. ## Key structures -- cgit v1.2.3