# Shared Tagging Rules Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Move the notmuch auto-tagging rules out of a hand-written shell hook into `~/.config/mailrules/rules.json`, a store both `mailctl` and `qtmaildir` read, and give qtmaildir a dialog to view, edit and dry-run them. **Architecture:** One JSON file is the source of truth. `mailctl` owns the shared Python library (`mailrules.py`) and the `post-new` hook that executes rules scoped to `tag:new`. qtmaildir owns a C++ reader/writer (`TagRules`) and the management dialog. A rule stores no scope, so the same rule serves the hook, a dry run, and a future backfill. Both readers preserve JSON fields they do not recognise, so neither tool owns the format. **Tech Stack:** Python 3 stdlib only (`json`, `pathlib`, `argparse`, `subprocess`) in `../mailctl`. Qt 6 (`QJsonDocument`, `QSaveFile`, `QDialog`) and `Qt6::Test` in this repo. `notmuch` CLI for the hook, `libnotmuch` via the existing `NotmuchWorker` for dry-run counts. **Spec:** `docs/superpowers/specs/2026-08-12-tagging-rules-design.md` **Repos:** Tasks 1-7 are in `../mailctl`. Tasks 8-13 are in this repo. Task 14 is the migration and touches neither repo's committed code. --- ## Correction to the spec, made before writing this plan The spec says qtmaildir's dry-run adds "a new worker slot, `countRules`". While planning, `NotmuchWorker::requestCounts(const QStringList &, quint64)` was found to already exist (`src/notmuchworker.h:131`), emitting `countsReady(const QVector &, quint64)`. It is generation-stamped and was built for the placeholder pane. It cannot be reused unchanged: it calls `notmuch_query_count_threads` (`src/notmuchworker.cpp:637`). A tagging rule tags MESSAGES, and a thread count misreports every rule that matches a few replies inside large threads. Task 10 therefore adds a message-counting slot beside it rather than a rule-specific one, which keeps the worker's vocabulary general. ## File structure | File | Repo | Responsibility | |---|---|---| | `mailrules.py` | mailctl | Load, validate, order, save `rules.json`. Unknown-key preservation. No notmuch calls. | | `post-new` | mailctl | Hook. Loads rules, applies them scoped to `tag:new`, consumes `tag:new` last. | | `mailctl.py` | mailctl | Adds the read-only `rules` subcommand. Modified, not created. | | `test_mailrules.py` | mailctl | Plain-assert tests for `mailrules.py`. | | `src/tagrules.h/.cpp` | qtmaildir | The same format in C++: parse, validate, save atomically. No widgets. | | `src/tagrulesdialog.h/.cpp` | qtmaildir | The management dialog. | | `tests/test_tagrules.cpp` | qtmaildir | Format tests. | | `src/notmuchworker.h/.cpp` | qtmaildir | Adds `requestMessageCounts`. Modified. | | `src/mainwindow.cpp` | qtmaildir | Menu action opening the dialog. Modified. | --- ## Task 1: The rules file loads **Files:** - Create: `../mailctl/mailrules.py` - Test: `../mailctl/test_mailrules.py` - [ ] **Step 1: Write the failing test** Create `../mailctl/test_mailrules.py`: ```python #!/usr/bin/env python3 # # Copyright (C) 2026 Danilo M. # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License version 2 as # published by the Free Software Foundation. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. """Self-checks for mailrules.py, the shared tagging-rule store. The risk in this file is the format, not the notmuch calls: a rule that silently loses a field on save, or one that sorts into the wrong stage, mis-tags real mail on the next sync and does it quietly. Run: ./test_mailrules.py """ import json import tempfile from pathlib import Path import mailrules def write_rules(tmp, payload): path = Path(tmp) / "rules.json" path.write_text(json.dumps(payload)) return path def test_loads_a_rule(): with tempfile.TemporaryDirectory() as tmp: path = write_rules(tmp, { "version": 1, "rules": [ { "id": "notify-forge", "stage": 50, "enabled": True, "add": ["notify/forge"], "remove": [], "query": "from:notifications@example.com", "note": "All repositories, not one project.", } ], }) store = mailrules.load(path) assert store.warnings == [], store.warnings assert len(store.rules) == 1 rule = store.rules[0] assert rule.id == "notify-forge" assert rule.stage == 50 assert rule.enabled is True assert rule.add == ["notify/forge"] assert rule.remove == [] assert rule.query == "from:notifications@example.com" assert rule.note == "All repositories, not one project." def test_defaults_are_applied(): """stage, enabled, remove and note are all optional in the file.""" with tempfile.TemporaryDirectory() as tmp: path = write_rules(tmp, { "version": 1, "rules": [{"id": "minimal", "add": ["x"], "query": "from:someone@example.com"}], }) store = mailrules.load(path) assert store.warnings == [], store.warnings rule = store.rules[0] assert rule.stage == 50 assert rule.enabled is True assert rule.remove == [] assert rule.note == "" def run_all(): for name, fn in sorted(globals().items()): if name.startswith("test_") and callable(fn): fn() print(f"ok {name}") if __name__ == "__main__": run_all() print("\nall passed") ``` - [ ] **Step 2: Run test to verify it fails** Run: `cd ../mailctl && ./test_mailrules.py` Expected: FAIL with `ModuleNotFoundError: No module named 'mailrules'` - [ ] **Step 3: Write minimal implementation** Create `../mailctl/mailrules.py`: ```python #!/usr/bin/env python3 # # Copyright (C) 2026 Danilo M. # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License version 2 as # published by the Free Software Foundation. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. """Shared notmuch tagging-rule store. The rules live in ~/.config/mailrules/rules.json and are read by both this tool and qtmaildir, so the format belongs to neither: a field one tool does not understand is preserved verbatim across a save by the other. A rule carries NO scope. The post-new hook supplies `tag:new`, a dry run supplies nothing and counts against the whole corpus. This is what lets one rule serve arrivals, a dry run, and (later) a backfill over history. Stdlib only, deliberately: this module is imported by a notmuch hook that runs on every sync, and mailctl has no dependencies to inherit. """ import json import os from dataclasses import dataclass, field from pathlib import Path FORMAT_VERSION = 1 DEFAULT_STAGE = 50 # Fields this version understands. Anything else in a rule object is kept in # `unknown` and written back untouched, which is what makes the file neutral # rather than this tool's file that another program may read. KNOWN_KEYS = {"id", "stage", "enabled", "add", "remove", "query", "note"} @dataclass class Rule: id: str query: str add: list = field(default_factory=list) remove: list = field(default_factory=list) stage: int = DEFAULT_STAGE enabled: bool = True note: str = "" unknown: dict = field(default_factory=dict) @dataclass class Store: rules: list = field(default_factory=list) warnings: list = field(default_factory=list) unknown: dict = field(default_factory=dict) def default_path(): """$XDG_CONFIG_HOME/mailrules/rules.json, or ~/.config/... as fallback. No hardcoded home directory: both tools must resolve the same path, and a user with XDG_CONFIG_HOME set expects it honoured. """ base = os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config" return Path(base) / "mailrules" / "rules.json" def load(path=None): """Read the store. Never raises for a bad file: problems land in Store.warnings and the offending rule is dropped, so one malformed rule cannot stop the other nineteen from running.""" path = Path(path) if path else default_path() store = Store() raw = json.loads(path.read_text()) for obj in raw.get("rules", []): store.rules.append(Rule( id=obj["id"], query=obj["query"], add=list(obj.get("add", [])), remove=list(obj.get("remove", [])), stage=int(obj.get("stage", DEFAULT_STAGE)), enabled=bool(obj.get("enabled", True)), note=obj.get("note", ""), unknown={k: v for k, v in obj.items() if k not in KNOWN_KEYS}, )) return store ``` - [ ] **Step 4: Run test to verify it passes** Run: `cd ../mailctl && ./test_mailrules.py` Expected: PASS, printing `ok test_defaults_are_applied`, `ok test_loads_a_rule`, `all passed` - [ ] **Step 5: Commit** ```bash cd ../mailctl chmod +x mailrules.py test_mailrules.py git add mailrules.py test_mailrules.py git commit -S -m "feat(rules): load a shared tagging-rule store The rules that tag incoming mail live in a notmuch post-new hook as hand-written shell. This is the first piece of moving them into a JSON store that both this tool and qtmaildir read. A rule carries no scope: the hook supplies tag:new, a dry run supplies nothing. Unknown fields are kept per rule so the format belongs to neither tool." ``` --- ## Task 2: A malformed rule is dropped with a warning, not fatal **Files:** - Modify: `../mailctl/mailrules.py` - Test: `../mailctl/test_mailrules.py` - [ ] **Step 1: Write the failing tests** Add to `../mailctl/test_mailrules.py`, above `run_all()`: ```python def test_a_bad_rule_is_dropped_and_the_rest_survive(): """One malformed rule must not stop the others. The hook runs every ten minutes on real mail; losing all tagging because of one typo is worse than losing one rule.""" with tempfile.TemporaryDirectory() as tmp: path = write_rules(tmp, { "version": 1, "rules": [ {"id": "good", "add": ["x"], "query": "from:a@example.com"}, {"id": "no-query", "add": ["y"]}, {"id": "no-tags", "query": "from:b@example.com"}, {"id": "bad id!", "add": ["z"], "query": "from:c@example.com"}, {"add": ["w"], "query": "from:d@example.com"}, ], }) store = mailrules.load(path) assert [r.id for r in store.rules] == ["good"] assert len(store.warnings) == 4, store.warnings joined = " ".join(store.warnings) assert "no-query" in joined assert "no-tags" in joined assert "bad id!" in joined def test_duplicate_ids_keep_the_first(): with tempfile.TemporaryDirectory() as tmp: path = write_rules(tmp, { "version": 1, "rules": [ {"id": "dup", "add": ["first"], "query": "from:a@example.com"}, {"id": "dup", "add": ["second"], "query": "from:b@example.com"}, ], }) store = mailrules.load(path) assert len(store.rules) == 1 assert store.rules[0].add == ["first"] assert any("dup" in w for w in store.warnings) def test_a_missing_file_is_empty_not_an_error(): """qtmaildir must open on a machine that has never written this file.""" with tempfile.TemporaryDirectory() as tmp: store = mailrules.load(Path(tmp) / "absent.json") assert store.rules == [] assert store.warnings == [] assert store.missing is True def test_unparseable_json_warns_and_yields_no_rules(): with tempfile.TemporaryDirectory() as tmp: path = Path(tmp) / "rules.json" path.write_text("{not json") store = mailrules.load(path) assert store.rules == [] assert len(store.warnings) == 1 assert store.failed is True def test_a_newer_format_version_is_refused(): """Guessing at semantics a later version defined is how a rule silently changes meaning. Refuse instead.""" with tempfile.TemporaryDirectory() as tmp: path = write_rules(tmp, { "version": 2, "rules": [{"id": "x", "add": ["a"], "query": "from:a@example.com"}], }) store = mailrules.load(path) assert store.rules == [] assert store.failed is True assert any("version" in w for w in store.warnings) ``` - [ ] **Step 2: Run tests to verify they fail** Run: `cd ../mailctl && ./test_mailrules.py` Expected: FAIL with `KeyError: 'query'` on the first new test - [ ] **Step 3: Write the implementation** In `../mailctl/mailrules.py`, add `re` to the imports: ```python import json import os import re from dataclasses import dataclass, field from pathlib import Path ``` Add after `KNOWN_KEYS`: ```python # An id is a handle, not a display name: a UI selects on it and a diff tracks # it. Tags may contain '/' and may be renamed; ids may not. ID_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$") ``` Replace the `Store` dataclass: ```python @dataclass class Store: rules: list = field(default_factory=list) warnings: list = field(default_factory=list) unknown: dict = field(default_factory=dict) # Distinguishes "no file yet" from "a file that would not load". The hook # treats them differently: the first is a fresh install, the second must # not consume tag:new. missing: bool = False failed: bool = False ``` Replace `load()` entirely: ```python def load(path=None): """Read the store. Never raises for a bad file: problems land in Store.warnings and the offending rule is dropped, so one malformed rule cannot stop the other nineteen from running.""" path = Path(path) if path else default_path() store = Store() if not path.exists(): store.missing = True return store try: raw = json.loads(path.read_text()) except (json.JSONDecodeError, OSError) as exc: store.warnings.append(f"{path}: cannot read: {exc}") store.failed = True return store if not isinstance(raw, dict): store.warnings.append(f"{path}: top level is not an object") store.failed = True return store version = raw.get("version", FORMAT_VERSION) if version != FORMAT_VERSION: store.warnings.append( f"{path}: format version {version} is newer than this tool " f"understands ({FORMAT_VERSION}); refusing to guess") store.failed = True return store store.unknown = {k: v for k, v in raw.items() if k not in ("version", "rules")} seen = set() for index, obj in enumerate(raw.get("rules", [])): rule = _parse_rule(obj, index, seen, store.warnings) if rule is not None: seen.add(rule.id) store.rules.append(rule) return store def _parse_rule(obj, index, seen, warnings): """One rule, or None with a warning appended. `index` names the rule when it has no usable id of its own.""" where = f"rule #{index + 1}" if not isinstance(obj, dict): warnings.append(f"{where}: not an object; dropped") return None rule_id = obj.get("id", "") if not isinstance(rule_id, str) or not ID_RE.match(rule_id): warnings.append( f"{where}: id '{rule_id}' is missing or not lowercase " f"letters, digits and dashes; dropped") return None if rule_id in seen: warnings.append(f"rule '{rule_id}': duplicate id; keeping the first") return None query = obj.get("query", "") if not isinstance(query, str) or not query.strip(): warnings.append(f"rule '{rule_id}': no query; dropped") return None add = [t for t in obj.get("add", []) if isinstance(t, str) and t.strip()] remove = [t for t in obj.get("remove", []) if isinstance(t, str) and t.strip()] if not add and not remove: warnings.append( f"rule '{rule_id}': adds and removes nothing; dropped") return None try: stage = int(obj.get("stage", DEFAULT_STAGE)) except (TypeError, ValueError): warnings.append( f"rule '{rule_id}': stage '{obj.get('stage')}' is not a " f"number; using {DEFAULT_STAGE}") stage = DEFAULT_STAGE return Rule( id=rule_id, query=query, add=add, remove=remove, stage=stage, enabled=bool(obj.get("enabled", True)), note=obj.get("note", "") if isinstance(obj.get("note", ""), str) else "", unknown={k: v for k, v in obj.items() if k not in KNOWN_KEYS}, ) ``` - [ ] **Step 4: Run tests to verify they pass** Run: `cd ../mailctl && ./test_mailrules.py` Expected: PASS, 7 `ok` lines then `all passed` - [ ] **Step 5: Commit** ```bash cd ../mailctl git add mailrules.py test_mailrules.py git commit -S -m "feat(rules): drop a malformed rule rather than the whole file One typo must not stop the other rules from tagging. A missing file and a file that will not parse are tracked separately: the hook may run on the first and must refuse on the second." ``` --- ## Task 3: Rules run in stage order **Files:** - Modify: `../mailctl/mailrules.py` - Test: `../mailctl/test_mailrules.py` - [ ] **Step 1: Write the failing test** Add to `../mailctl/test_mailrules.py`: ```python def test_ordered_sorts_by_stage_then_file_position(): """Account tags must run before topic rules. Ties keep file order, so the file still reads as a sequence.""" with tempfile.TemporaryDirectory() as tmp: path = write_rules(tmp, { "version": 1, "rules": [ {"id": "topic-b", "stage": 50, "add": ["b"], "query": "from:b@example.com"}, {"id": "account", "stage": 10, "add": ["acct"], "query": "path:\"work/**\""}, {"id": "topic-a", "stage": 50, "add": ["a"], "query": "from:a@example.com"}, ], }) store = mailrules.load(path) assert [r.id for r in mailrules.ordered(store.rules)] == [ "account", "topic-b", "topic-a"] def test_ordered_skips_disabled_rules(): with tempfile.TemporaryDirectory() as tmp: path = write_rules(tmp, { "version": 1, "rules": [ {"id": "on", "add": ["a"], "query": "from:a@example.com"}, {"id": "off", "add": ["b"], "query": "from:b@example.com", "enabled": False}, ], }) store = mailrules.load(path) assert [r.id for r in mailrules.ordered(store.rules)] == ["on"] # The disabled rule is still LOADED, so a UI can show and re-enable it. assert [r.id for r in store.rules] == ["on", "off"] ``` - [ ] **Step 2: Run tests to verify they fail** Run: `cd ../mailctl && ./test_mailrules.py` Expected: FAIL with `AttributeError: module 'mailrules' has no attribute 'ordered'` - [ ] **Step 3: Write the implementation** Add to `../mailctl/mailrules.py`: ```python def ordered(rules): """Enabled rules in execution order: by stage ascending, ties by position. `sorted` is stable, so sorting on stage alone preserves file order within a stage. That is the tie-break the format promises, and it is why this does not sort on (stage, id): an id-sorted tie would reorder rules a user deliberately sequenced. """ return sorted([r for r in rules if r.enabled], key=lambda r: r.stage) ``` - [ ] **Step 4: Run tests to verify they pass** Run: `cd ../mailctl && ./test_mailrules.py` Expected: PASS, 9 `ok` lines - [ ] **Step 5: Commit** ```bash cd ../mailctl git add mailrules.py test_mailrules.py git commit -S -m "feat(rules): order rules by stage, ties by file position Account tags must run before topic rules, which is what the stage field is for. Disabled rules stay loaded so a UI can re-enable them." ``` --- ## Task 4: Saving preserves fields this version does not know **Files:** - Modify: `../mailctl/mailrules.py` - Test: `../mailctl/test_mailrules.py` - [ ] **Step 1: Write the failing test** Add to `../mailctl/test_mailrules.py`: ```python def test_save_round_trips_unknown_fields(): """The neutrality guarantee. If this tool strips a field qtmaildir added, the file is this tool's file that qtmaildir may read.""" with tempfile.TemporaryDirectory() as tmp: path = write_rules(tmp, { "version": 1, "future_top_level": {"set_by": "another tool"}, "rules": [{ "id": "keeper", "add": ["x"], "query": "from:a@example.com", "future_field": [1, 2, 3], }], }) store = mailrules.load(path) assert store.rules[0].unknown == {"future_field": [1, 2, 3]} mailrules.save(store, path) raw = json.loads(path.read_text()) assert raw["future_top_level"] == {"set_by": "another tool"} assert raw["rules"][0]["future_field"] == [1, 2, 3] assert raw["rules"][0]["id"] == "keeper" assert raw["version"] == 1 def test_save_is_atomic(): """A reader must never see a half-written file: the hook runs every ten minutes and a truncated read would be a failed sync.""" with tempfile.TemporaryDirectory() as tmp: path = Path(tmp) / "rules.json" store = mailrules.Store(rules=[ mailrules.Rule(id="a", query="from:a@example.com", add=["x"])]) mailrules.save(store, path) # The temp file the write went through must not be left behind. assert [p.name for p in Path(tmp).iterdir()] == ["rules.json"] assert json.loads(path.read_text())["rules"][0]["id"] == "a" def test_save_creates_the_directory(): with tempfile.TemporaryDirectory() as tmp: path = Path(tmp) / "nested" / "rules.json" mailrules.save(mailrules.Store(), path) assert path.exists() assert json.loads(path.read_text()) == {"version": 1, "rules": []} ``` - [ ] **Step 2: Run tests to verify they fail** Run: `cd ../mailctl && ./test_mailrules.py` Expected: FAIL with `AttributeError: module 'mailrules' has no attribute 'save'` - [ ] **Step 3: Write the implementation** Add `import tempfile` to `../mailctl/mailrules.py`'s imports, then add: ```python def save(store, path=None): """Write the store atomically: a temp file in the same directory, then rename. Rename within a filesystem is atomic, so a concurrent reader sees either the old file or the new one and never a partial write. There is no locking. Last writer wins on a true collision, which is accepted for a single-user setup; the failure that would actually hurt is a truncated read by the hook, and rename eliminates it. """ path = Path(path) if path else default_path() path.parent.mkdir(parents=True, exist_ok=True) payload = dict(store.unknown) payload["version"] = FORMAT_VERSION payload["rules"] = [_rule_to_dict(r) for r in store.rules] # delete=False plus an explicit replace: NamedTemporaryFile would unlink # the file on close, and the rename is the whole point. handle = tempfile.NamedTemporaryFile( mode="w", dir=path.parent, prefix=".rules-", suffix=".tmp", delete=False) try: with handle: json.dump(payload, handle, indent=2, ensure_ascii=False) handle.write("\n") handle.flush() os.fsync(handle.fileno()) os.replace(handle.name, path) except BaseException: # A failed write must not leave the temp file beside the real one. try: os.unlink(handle.name) except OSError: pass raise def _rule_to_dict(rule): """Known fields first in a stable order, then anything this version did not understand. Stable ordering keeps a diff of this file readable.""" out = { "id": rule.id, "stage": rule.stage, "enabled": rule.enabled, "add": list(rule.add), "remove": list(rule.remove), "query": rule.query, "note": rule.note, } out.update(rule.unknown) return out ``` - [ ] **Step 4: Run tests to verify they pass** Run: `cd ../mailctl && ./test_mailrules.py` Expected: PASS, 12 `ok` lines - [ ] **Step 5: Commit** ```bash cd ../mailctl git add mailrules.py test_mailrules.py git commit -S -m "feat(rules): save atomically, preserving unknown fields Write to a temp file and rename, so the hook can never read a partial file. Fields this version does not understand round-trip untouched, which is what makes the format belong to neither tool." ``` --- ## Task 5: The scoped query the hook will run **Files:** - Modify: `../mailctl/mailrules.py` - Test: `../mailctl/test_mailrules.py` - [ ] **Step 1: Write the failing test** Add to `../mailctl/test_mailrules.py`: ```python def test_scoped_query_parenthesises_the_rule(): """Without the parentheses `tag:new and a or b` binds as `(tag:new and a) or b`, and the rule matches every message in the corpus satisfying b rather than only new arrivals. Several real rules are a disjunction of senders, so this is the difference between tagging four messages and tagging four thousand.""" rule = mailrules.Rule( id="disjunction", query="from:a@example.com or from:b@example.com", add=["promo"]) assert mailrules.scoped_query(rule, "tag:new") == ( "tag:new and (from:a@example.com or from:b@example.com)") def test_scoped_query_with_no_scope_is_the_bare_query(): """A dry run counts against the whole corpus, which is what makes the same rule answer 'what would this tag on arrival' and 'what does this match in all my mail'.""" rule = mailrules.Rule(id="x", query="from:a@example.com", add=["y"]) assert mailrules.scoped_query(rule, None) == "from:a@example.com" assert mailrules.scoped_query(rule, "") == "from:a@example.com" def test_tag_arguments(): rule = mailrules.Rule(id="x", query="from:a@example.com", add=["one", "two"], remove=["three"]) assert mailrules.tag_arguments(rule) == ["+one", "+two", "-three"] ``` - [ ] **Step 2: Run tests to verify they fail** Run: `cd ../mailctl && ./test_mailrules.py` Expected: FAIL with `AttributeError: module 'mailrules' has no attribute 'scoped_query'` - [ ] **Step 3: Write the implementation** Add to `../mailctl/mailrules.py`: ```python def scoped_query(rule, scope): """The rule's query narrowed by `scope`, or the bare query when scope is empty. The parentheses are load-bearing. notmuch's `and` binds tighter than `or`, so `tag:new and a or b` means `(tag:new and a) or b`: a rule that is a disjunction of senders would escape its scope and match the whole corpus. Do not remove them, and do not build this string anywhere else. """ if not scope: return rule.query return f"{scope} and ({rule.query})" def tag_arguments(rule): """The +tag/-tag arguments for `notmuch tag`, adds before removes.""" return [f"+{t}" for t in rule.add] + [f"-{t}" for t in rule.remove] ``` - [ ] **Step 4: Run tests to verify they pass** Run: `cd ../mailctl && ./test_mailrules.py` Expected: PASS, 15 `ok` lines - [ ] **Step 5: Commit** ```bash cd ../mailctl git add mailrules.py test_mailrules.py git commit -S -m "feat(rules): build the scoped query in one place A rule stores no scope. The hook supplies tag:new, a dry run supplies nothing. The parentheses around the rule's own query are what stop a disjunction of senders from escaping the scope and matching everything." ``` --- ## Task 6: The post-new hook **Files:** - Create: `../mailctl/post-new` - Test: manual, per the steps below This task has no unit test. The hook's logic is a loop over already-tested functions plus `subprocess` calls to `notmuch`; a test would mostly assert that mocks were called. Its real risks (does it refuse when rules fail to load, does it consume `tag:new` only on success) are verified against a throwaway notmuch database in Task 7. - [ ] **Step 1: Write the hook** Create `../mailctl/post-new`: ```python #!/usr/bin/env python3 # # Copyright (C) 2026 Danilo M. # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License version 2 as # published by the Free Software Foundation. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. """notmuch post-new hook: auto-tag incoming mail from the shared rule store. Runs after every `notmuch new`. Reads ~/.config/mailrules/rules.json and applies each enabled rule scoped to `tag:new`, in stage order, then consumes the `tag:new` marker. TAG-ONLY in practice: the rules currently in use add tags and remove none. Nothing here forbids a `remove`, but note that touching `unread` would rewrite Maildir filenames and propagate to IMAP on the next mbsync, because maildir.synchronize_flags is true. Requires `new` in [new] tags= in ~/.notmuch-config. Without it every scoped query matches nothing and this silently no-ops. Install: copy to /.notmuch/hooks/post-new, with mailrules.py importable (same directory, or on PYTHONPATH). """ import subprocess import sys from pathlib import Path sys.path.insert(0, str(Path(__file__).resolve().parent)) import mailrules SCOPE = "tag:new" def log(message): print(f"post-new: {message}", file=sys.stderr) def run_tag(arguments, query): result = subprocess.run(["notmuch", "tag"] + arguments + ["--", query], capture_output=True, text=True) if result.returncode != 0: log(f"notmuch tag failed: {result.stderr.strip()}") return False return True def main(): store = mailrules.load() # A file that will not load must NOT reach the consumer below. If the # marker were cleared while the rules did not run, that mail could never # be tagged by these rules again: the failure is silent, permanent, and # invisible until someone notices a gap months later. Leaving tag:new in # place makes the next successful run catch up instead. if store.failed: for warning in store.warnings: log(warning) log("rules did not load; leaving tag:new in place") return 1 if store.missing: log("no rules file; nothing to do") return 0 # A dropped rule is not fatal, but it must be visible: this goes to the # sync log, which is where someone looks when a tag stops appearing. for warning in store.warnings: log(warning) rules = mailrules.ordered(store.rules) for rule in rules: query = mailrules.scoped_query(rule, SCOPE) if not run_tag(mailrules.tag_arguments(rule), query): log(f"rule '{rule.id}' failed; leaving tag:new in place") return 1 # Only after every rule succeeded. A failure part way through leaves the # marker set, so re-running the hook is safe and finishes the work. if not run_tag(["-new"], SCOPE): return 1 log(f"applied {len(rules)} rule(s)") return 0 if __name__ == "__main__": sys.exit(main()) ``` - [ ] **Step 2: Verify it refuses to run with no rules file** Run: ```bash cd ../mailctl && chmod +x post-new XDG_CONFIG_HOME=/tmp/no-such-dir ./post-new; echo "exit=$?" ``` Expected: `post-new: no rules file; nothing to do` and `exit=0` - [ ] **Step 3: Verify it refuses on a broken rules file** Run: ```bash mkdir -p /tmp/rulestest/mailrules && echo '{bad' > /tmp/rulestest/mailrules/rules.json cd ../mailctl && XDG_CONFIG_HOME=/tmp/rulestest ./post-new; echo "exit=$?" ``` Expected: a `cannot read` warning, `leaving tag:new in place`, and `exit=1` - [ ] **Step 4: Commit** ```bash cd ../mailctl git add post-new git commit -S -m "feat(rules): post-new hook driven by the rule store Applies each enabled rule scoped to tag:new in stage order, then consumes the marker. A rules file that will not load leaves tag:new alone: clearing it while the rules did not run would permanently orphan that mail." ``` --- ## Task 7: The hook is verified against a throwaway database **Files:** - Create: `../mailctl/test_post_new.py` - [ ] **Step 1: Write the failing test** Create `../mailctl/test_post_new.py`: ```python #!/usr/bin/env python3 # # Copyright (C) 2026 Danilo M. # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License version 2 as # published by the Free Software Foundation. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. """End-to-end checks for the post-new hook against a throwaway notmuch database. Nothing here touches the user's real mail: NOTMUCH_CONFIG points at a generated maildir under a temp directory. The properties worth proving are the ones that cannot be unit-tested from mailrules.py alone: - a rule actually tags the mail its query matches, and only that mail - the tag:new marker is consumed on success - the marker SURVIVES when a rule fails, so a re-run catches up Run: ./test_post_new.py (requires notmuch on PATH) """ import json import os import subprocess import tempfile from pathlib import Path HOOK = Path(__file__).resolve().parent / "post-new" def make_message(maildir, name, sender, subject): path = maildir / "new" / name path.write_text( f"From: {sender}\n" f"To: you@example.org\n" f"Subject: {subject}\n" f"Message-Id: <{name}@example.org>\n" f"Date: Mon, 11 Aug 2026 10:00:00 +0000\n" f"\nbody\n") def setup_database(tmp): """A maildir with three messages, indexed, every message carrying the `new` marker the rules key off.""" maildir = Path(tmp) / "Mail" for sub in ("new", "cur", "tmp"): (maildir / sub).mkdir(parents=True) make_message(maildir, "one", "notifications@example.com", "a notification") make_message(maildir, "two", "friend@example.org", "a real message") make_message(maildir, "three", "promo@example.net", "an advertisement") config = Path(tmp) / "notmuch-config" config.write_text( f"[database]\npath={maildir}\n\n" f"[new]\ntags=new;unread;inbox\n\n" f"[user]\nname=Test\nprimary_email=you@example.org\n") env = dict(os.environ) env["NOTMUCH_CONFIG"] = str(config) env["XDG_CONFIG_HOME"] = str(Path(tmp) / "config") subprocess.run(["notmuch", "new"], env=env, capture_output=True, check=True) return env def write_rules(env, rules): path = Path(env["XDG_CONFIG_HOME"]) / "mailrules" / "rules.json" path.parent.mkdir(parents=True, exist_ok=True) path.write_text(json.dumps({"version": 1, "rules": rules})) def count(env, query): out = subprocess.run(["notmuch", "count", query], env=env, capture_output=True, text=True, check=True) return int(out.stdout.strip()) def test_a_rule_tags_only_what_it_matches(): with tempfile.TemporaryDirectory() as tmp: env = setup_database(tmp) write_rules(env, [{ "id": "notify", "add": ["notify/forge"], "query": "from:notifications@example.com", }]) assert count(env, "tag:new") == 3 result = subprocess.run([str(HOOK)], env=env, capture_output=True, text=True) assert result.returncode == 0, result.stderr assert count(env, "tag:notify/forge") == 1 assert count(env, "tag:notify/forge and from:friend@example.org") == 0 # The marker is consumed, so the next sync's rules see only new mail. assert count(env, "tag:new") == 0 def test_stage_order_is_honoured(): with tempfile.TemporaryDirectory() as tmp: env = setup_database(tmp) write_rules(env, [ {"id": "late", "stage": 50, "add": ["second"], "query": "tag:first"}, {"id": "early", "stage": 10, "add": ["first"], "query": "from:notifications@example.com"}, ]) subprocess.run([str(HOOK)], env=env, capture_output=True, check=True) # `late` matches only what `early` tagged, so a wrong order gives 0. assert count(env, "tag:second") == 1 def test_a_failing_rule_leaves_the_marker_in_place(): """The property that makes a re-run safe. An invalid query fails the notmuch call, and tag:new must survive so the next run catches up.""" with tempfile.TemporaryDirectory() as tmp: env = setup_database(tmp) write_rules(env, [{ "id": "broken", "add": ["x"], "query": "from:((((", }]) result = subprocess.run([str(HOOK)], env=env, capture_output=True, text=True) assert result.returncode == 1 assert count(env, "tag:new") == 3 def test_a_disjunction_stays_inside_its_scope(): """The parenthesisation guard, end to end. Both senders are already indexed and out of tag:new after a first run; a rule that escaped its scope would tag them anyway.""" with tempfile.TemporaryDirectory() as tmp: env = setup_database(tmp) write_rules(env, [{"id": "noop", "add": ["pass-one"], "query": "from:nobody@example.invalid"}]) subprocess.run([str(HOOK)], env=env, capture_output=True, check=True) assert count(env, "tag:new") == 0 write_rules(env, [{ "id": "disjunction", "add": ["promo"], "query": "from:friend@example.org or from:promo@example.net", }]) subprocess.run([str(HOOK)], env=env, capture_output=True, check=True) # Nothing carries tag:new any more, so a correctly scoped rule tags # nothing. Unparenthesised, the `or` branch would tag one message. assert count(env, "tag:promo") == 0 def run_all(): for name, fn in sorted(globals().items()): if name.startswith("test_") and callable(fn): fn() print(f"ok {name}") if __name__ == "__main__": run_all() print("\nall passed") ``` - [ ] **Step 2: Run the test to verify it fails** First confirm the guard test genuinely detects the bug it targets. Temporarily break the parenthesisation in `mailrules.py`: ```python return f"{scope} and {rule.query}" ``` Run: `cd ../mailctl && chmod +x test_post_new.py && ./test_post_new.py` Expected: FAIL on `test_a_disjunction_stays_inside_its_scope` with `assert 1 == 0` - [ ] **Step 3: Restore the correct implementation** Put the parentheses back in `../mailctl/mailrules.py`: ```python return f"{scope} and ({rule.query})" ``` - [ ] **Step 4: Run the tests to verify they pass** Run: `cd ../mailctl && ./test_post_new.py && ./test_mailrules.py` Expected: both PASS, 4 `ok` lines then 15 `ok` lines - [ ] **Step 5: Commit** ```bash cd ../mailctl git add test_post_new.py git commit -S -m "test(rules): verify the hook against a throwaway database Covers what unit tests cannot: that a rule tags only what it matches, that stage order decides what a later rule can see, that a failed rule leaves tag:new in place, and that a disjunction stays inside its scope. The last one was confirmed to fail against unparenthesised code." ``` --- ## Task 8: `mailctl rules list` and `show` **Files:** - Modify: `../mailctl/mailctl.py` - Modify: `../mailctl/CLAUDE.md` - Modify: `../mailctl/README.md` - [ ] **Step 1: Add the commands** In `../mailctl/mailctl.py`, add the import beside the existing ones: ```python import mailrules ``` Add these functions immediately before `def build_parser():`: ```python def cmd_rules_list(args): store = mailrules.load() for warning in store.warnings: print(f"warning: {warning}", file=sys.stderr) if store.missing: print(f"No rules file at {mailrules.default_path()}", file=sys.stderr) return for rule in mailrules.ordered(store.rules) if args.enabled_only \ else store.rules: state = " " if rule.enabled else "-" tags = " ".join(mailrules.tag_arguments(rule)) print(f"{state} {rule.stage:>4} {rule.id:<28.28} {tags}") total = len(store.rules) disabled = sum(1 for r in store.rules if not r.enabled) print(f"\n{total} rule(s), {disabled} disabled", file=sys.stderr) def cmd_rules_show(args): store = mailrules.load() for rule in store.rules: if rule.id != args.id: continue print(f"id: {rule.id}") print(f"stage: {rule.stage}") print(f"enabled: {rule.enabled}") print(f"add: {', '.join(rule.add) or '(none)'}") print(f"remove: {', '.join(rule.remove) or '(none)'}") print(f"query: {rule.query}") if rule.note: print(f"note: {rule.note}") return print(f"No rule with id '{args.id}'", file=sys.stderr) sys.exit(1) ``` In `build_parser()`, add before the final `return p`: ```python sp = sub.add_parser("rules", help="inspect the shared tagging rules " "(read-only)") rules_sub = sp.add_subparsers(dest="rules_command", required=True) rp = rules_sub.add_parser("list", help="list every rule in stage order") rp.add_argument("--enabled-only", action="store_true", help="only the rules the hook would run") rp.set_defaults(func=cmd_rules_list) rp = rules_sub.add_parser("show", help="show one rule in full") rp.add_argument("id") rp.set_defaults(func=cmd_rules_show) ``` - [ ] **Step 2: Verify against a scratch rules file** Run: ```bash mkdir -p /tmp/rulesdemo/mailrules cat > /tmp/rulesdemo/mailrules/rules.json <<'JSON' {"version": 1, "rules": [ {"id": "account-work", "stage": 10, "add": ["account-work"], "query": "path:\"work/**\"", "note": "Runs before topic rules."}, {"id": "notify-forge", "stage": 50, "add": ["notify/forge"], "query": "from:notifications@example.com"}, {"id": "old-rule", "stage": 50, "add": ["x"], "query": "from:dead@example.com", "enabled": false} ]} JSON cd ../mailctl XDG_CONFIG_HOME=/tmp/rulesdemo ./mailctl.py rules list XDG_CONFIG_HOME=/tmp/rulesdemo ./mailctl.py rules show account-work ``` Expected: three rules listed with `-` against `old-rule`, `3 rule(s), 1 disabled`, then the full `account-work` rule including its note. - [ ] **Step 3: Document the commands** In `../mailctl/README.md` and `../mailctl/CLAUDE.md`, add to the command list under "Running": ``` ./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 ``` In `../mailctl/CLAUDE.md`, add to the "Safety model" section: ```markdown - **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. ``` - [ ] **Step 4: Commit** ```bash cd ../mailctl git add mailctl.py README.md CLAUDE.md git commit -S -m "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." ``` --- ## Task 9: `mailctl rules dry-run` **Files:** - Modify: `../mailctl/mailctl.py` - [ ] **Step 1: Add the command** In `../mailctl/mailctl.py`, add after `cmd_rules_show`: ```python def cmd_rules_dry_run(args): """What each rule matches right now. Two numbers, because they answer different questions: the corpus count says whether a rule is still doing anything and whether it would bury real correspondence, the pending count says what the next sync would tag.""" store = mailrules.load() rules = [r for r in store.rules if not args.id or r.id == args.id] if not rules: print(f"No rule with id '{args.id}'", file=sys.stderr) sys.exit(1) print(f"{'rule':<28} {'corpus':>8} {'pending':>8}") for rule in rules: corpus = run_notmuch(["count", mailrules.scoped_query(rule, None)]) pending = run_notmuch(["count", mailrules.scoped_query(rule, "tag:new")]) state = "" if rule.enabled else " (disabled)" print(f"{rule.id:<28.28} {corpus.strip():>8} " f"{pending.strip():>8}{state}") ``` In `build_parser()`, beside the other `rules` subcommands: ```python rp = rules_sub.add_parser("dry-run", help="count what each rule matches, changing " "nothing") rp.add_argument("id", nargs="?", help="one rule, default is all") rp.set_defaults(func=cmd_rules_dry_run) ``` - [ ] **Step 2: Verify against the real index** Run: ```bash cd ../mailctl && XDG_CONFIG_HOME=/tmp/rulesdemo ./mailctl.py rules dry-run ``` Expected: a table of three rules with corpus counts from the real database and `0` pending for each (nothing carries `tag:new` between syncs). - [ ] **Step 3: Commit** ```bash cd ../mailctl git add mailctl.py git commit -S -m "feat(rules): dry-run counts what a rule matches Two numbers per rule: what it matches across all mail, and what it would tag on the next sync. The first is what decides whether a rule is still earning its place." ``` --- ## Task 10: qtmaildir parses the same file **Files:** - Create: `src/tagrules.h`, `src/tagrules.cpp` - Create: `tests/test_tagrules.cpp` - Modify: `src/CMakeLists.txt`, `tests/CMakeLists.txt` - [ ] **Step 1: Write the failing test** Create `tests/test_tagrules.cpp`: ```cpp /* * qtmaildir - a Qt6 mail client for notmuch-indexed Maildirs * Copyright (C) 2026 Danilo M. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License version 2 as * published by the Free Software Foundation. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */ #include #include #include "tagrules.h" /// The risk in TagRules is the format, not painting: a field silently dropped /// on save mis-tags real mail on the next sync, and does it quietly. These /// tests are therefore about round-trips and rejections, and the file they /// read is byte-for-byte what mailctl writes. class TestTagRules : public QObject { Q_OBJECT private slots: void aRuleLoadsWithEveryField(); void absentFieldsTakeTheirDefaults(); void aMalformedRuleIsDroppedWithAWarning(); void unknownFieldsSurviveASave(); void stageOrderPutsAccountsFirst(); void aQueryWithQuotesRoundTrips(); void aMissingFileIsEmptyNotAnError(); void aNewerVersionIsRefused(); private: QString writeRules(const QString &json); QTemporaryDir m_dir; }; QString TestTagRules::writeRules(const QString &json) { const QString path = m_dir.filePath(QStringLiteral("rules.json")); QFile file(path); if (!file.open(QIODevice::WriteOnly | QIODevice::Truncate)) return QString(); file.write(json.toUtf8()); file.close(); return path; } void TestTagRules::aRuleLoadsWithEveryField() { const QString path = writeRules(R"({ "version": 1, "rules": [{ "id": "notify-forge", "stage": 50, "enabled": true, "add": ["notify/forge"], "remove": [], "query": "from:notifications@example.com", "note": "All repositories, not one project." }] })"); TagRules rules; rules.load(path); QVERIFY2(rules.warnings().isEmpty(), qPrintable(rules.warnings().join(QStringLiteral("; ")))); QCOMPARE(rules.rules().size(), 1); const TagRule &rule = rules.rules().first(); QCOMPARE(rule.id, QStringLiteral("notify-forge")); QCOMPARE(rule.stage, 50); QVERIFY(rule.enabled); QCOMPARE(rule.add, QStringList{ QStringLiteral("notify/forge") }); QVERIFY(rule.remove.isEmpty()); QCOMPARE(rule.query, QStringLiteral("from:notifications@example.com")); QCOMPARE(rule.note, QStringLiteral("All repositories, not one project.")); } void TestTagRules::absentFieldsTakeTheirDefaults() { const QString path = writeRules(R"({ "version": 1, "rules": [{"id": "minimal", "add": ["x"], "query": "from:a@example.com"}] })"); TagRules rules; rules.load(path); QVERIFY(rules.warnings().isEmpty()); const TagRule &rule = rules.rules().first(); QCOMPARE(rule.stage, 50); QVERIFY(rule.enabled); QVERIFY(rule.remove.isEmpty()); QVERIFY(rule.note.isEmpty()); } void TestTagRules::aMalformedRuleIsDroppedWithAWarning() { // One bad rule must not cost the others. Four separate defects, and the // good rule sits first so a parser that stops at the first problem is // caught by the count rather than by an empty list. const QString path = writeRules(R"({ "version": 1, "rules": [ {"id": "good", "add": ["x"], "query": "from:a@example.com"}, {"id": "no-query", "add": ["y"]}, {"id": "no-tags", "query": "from:b@example.com"}, {"id": "Bad Id", "add": ["z"], "query": "from:c@example.com"} ] })"); TagRules rules; rules.load(path); QCOMPARE(rules.rules().size(), 1); QCOMPARE(rules.rules().first().id, QStringLiteral("good")); QCOMPARE(rules.warnings().size(), 3); } void TestTagRules::unknownFieldsSurviveASave() { // The neutrality guarantee. If qtmaildir strips a field mailctl wrote, // the file is qtmaildir's file that mailctl may read. const QString path = writeRules(R"({ "version": 1, "future_top_level": {"set_by": "another tool"}, "rules": [{ "id": "keeper", "add": ["x"], "query": "from:a@example.com", "future_field": [1, 2, 3] }] })"); TagRules rules; rules.load(path); QVERIFY(rules.save(path)); QFile file(path); QVERIFY(file.open(QIODevice::ReadOnly)); const QJsonObject root = QJsonDocument::fromJson(file.readAll()).object(); QCOMPARE(root.value(QStringLiteral("future_top_level")) .toObject().value(QStringLiteral("set_by")).toString(), QStringLiteral("another tool")); const QJsonObject saved = root.value(QStringLiteral("rules")).toArray().first().toObject(); QCOMPARE(saved.value(QStringLiteral("future_field")).toArray().size(), 3); QCOMPARE(saved.value(QStringLiteral("id")).toString(), QStringLiteral("keeper")); } void TestTagRules::stageOrderPutsAccountsFirst() { const QString path = writeRules(R"({ "version": 1, "rules": [ {"id": "topic-b", "stage": 50, "add": ["b"], "query": "from:b@example.com"}, {"id": "account", "stage": 10, "add": ["acct"], "query": "path:\"work/**\""}, {"id": "topic-a", "stage": 50, "add": ["a"], "query": "from:a@example.com"}, {"id": "off", "stage": 20, "add": ["c"], "query": "from:c@example.com", "enabled": false} ] })"); TagRules rules; rules.load(path); QStringList ids; for (const TagRule &rule : rules.ordered()) ids.append(rule.id); // Stage ascending, ties in file order, disabled excluded. QCOMPARE(ids, (QStringList{ QStringLiteral("account"), QStringLiteral("topic-b"), QStringLiteral("topic-a") })); // Still loaded, so the dialog can show and re-enable it. QCOMPARE(rules.rules().size(), 4); } void TestTagRules::aQueryWithQuotesRoundTrips() { // Not hypothetical: every account rule is written path:"account/**". const QString path = writeRules(R"({ "version": 1, "rules": [{"id": "account", "add": ["acct"], "query": "path:\"work-account/**\""}] })"); TagRules rules; rules.load(path); QCOMPARE(rules.rules().first().query, QStringLiteral("path:\"work-account/**\"")); QVERIFY(rules.save(path)); TagRules reloaded; reloaded.load(path); QVERIFY(reloaded.warnings().isEmpty()); QCOMPARE(reloaded.rules().first().query, QStringLiteral("path:\"work-account/**\"")); } void TestTagRules::aMissingFileIsEmptyNotAnError() { // qtmaildir must open on a machine that has never written this file. TagRules rules; rules.load(m_dir.filePath(QStringLiteral("absent.json"))); QVERIFY(rules.rules().isEmpty()); QVERIFY(rules.warnings().isEmpty()); QVERIFY(rules.missing()); } void TestTagRules::aNewerVersionIsRefused() { const QString path = writeRules(R"({ "version": 2, "rules": [{"id": "x", "add": ["a"], "query": "from:a@example.com"}] })"); TagRules rules; rules.load(path); QVERIFY(rules.rules().isEmpty()); QCOMPARE(rules.warnings().size(), 1); } QTEST_MAIN(TestTagRules) #include "test_tagrules.moc" ``` - [ ] **Step 2: Register the test and run it to verify it fails** Add to `tests/CMakeLists.txt`, after `add_qtmaildir_test(tagdialog)`: ```cmake add_qtmaildir_test(tagrules) ``` Run: `cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug && cmake --build build` Expected: FAIL, `fatal error: tagrules.h: No such file or directory` - [ ] **Step 3: Write the header** Create `src/tagrules.h`: ```cpp /* * qtmaildir - a Qt6 mail client for notmuch-indexed Maildirs * Copyright (C) 2026 Danilo M. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License version 2 as * published by the Free Software Foundation. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */ #pragma once #include #include #include #include /// One auto-tagging rule, as stored in ~/.config/mailrules/rules.json. /// /// A rule carries NO scope. The notmuch post-new hook supplies `tag:new`, a /// dry run supplies nothing and counts against the whole corpus. That split is /// what lets one rule answer both "what would this tag on arrival" and "what /// does this match in all my mail". struct TagRule { QString id; ///< Stable handle, [a-z0-9-]. Never the tag name: tags ///< contain '/' and can be renamed. QString query; ///< notmuch query, unscoped. QString note; ///< Why the rule is shaped this way. Shown in the dialog. QStringList add; QStringList remove; int stage = 50; ///< Ascending. Account tags 10, topic rules 50. bool enabled = true; /// Fields this version of qtmaildir does not understand, kept verbatim and /// written back on save. Without this, one save from here silently strips /// whatever a newer mailctl wrote, and the shared format would belong to /// whichever tool saved last. QJsonObject unknown; }; /// Reads and writes the shared rule store. /// /// Degrades rather than refusing, exactly as Config does: a malformed rule is /// dropped with a warning and the rest still load, because one typo must not /// cost every rule. qtmaildir must never fail to open because of this file. class TagRules { public: /// $XDG_CONFIG_HOME/mailrules/rules.json, or ~/.config/... as fallback. /// Deliberately not under qtmaildir's own config directory: mailctl reads /// the same file and neither tool owns it. static QString defaultPath(); /// Replaces the current contents. Never throws; see warnings(). void load(const QString &path = QString()); /// Atomic: QSaveFile writes a temporary and renames, so the hook can never /// read a partial file. Returns false if the write failed. bool save(const QString &path = QString()) const; QList rules() const { return m_rules; } void setRules(const QList &rules) { m_rules = rules; } /// Enabled rules in execution order: stage ascending, ties in file order. QList ordered() const; QStringList warnings() const { return m_warnings; } /// No file yet, as distinct from a file that would not load. A fresh /// install is not an error and must not be reported as one. bool missing() const { return m_missing; } private: QList m_rules; QStringList m_warnings; QJsonObject m_unknown; ///< Unrecognised top-level keys. bool m_missing = false; }; ``` - [ ] **Step 4: Write the implementation** Create `src/tagrules.cpp`: ```cpp /* * qtmaildir - a Qt6 mail client for notmuch-indexed Maildirs * Copyright (C) 2026 Danilo M. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License version 2 as * published by the Free Software Foundation. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */ #include "tagrules.h" #include #include #include #include #include #include #include #include namespace { constexpr int kFormatVersion = 1; constexpr int kDefaultStage = 50; /// Fields this version understands. Anything else is preserved. bool isKnownKey(const QString &key) { static const QStringList known{ QStringLiteral("id"), QStringLiteral("stage"), QStringLiteral("enabled"), QStringLiteral("add"), QStringLiteral("remove"), QStringLiteral("query"), QStringLiteral("note"), }; return known.contains(key); } QStringList stringsOf(const QJsonValue &value) { QStringList out; for (const QJsonValue &entry : value.toArray()) { const QString text = entry.toString().trimmed(); if (!text.isEmpty()) out.append(text); } return out; } } // namespace QString TagRules::defaultPath() { // Not QStandardPaths::ConfigLocation: that appends the organization and // application names, which would put the file under qtmaildir's own // directory. mailctl reads this path too, so it must be tool-neutral. QString base = qEnvironmentVariable("XDG_CONFIG_HOME"); if (base.isEmpty()) base = QDir::homePath() + QStringLiteral("/.config"); return base + QStringLiteral("/mailrules/rules.json"); } void TagRules::load(const QString &path) { const QString target = path.isEmpty() ? defaultPath() : path; m_rules.clear(); m_warnings.clear(); m_unknown = QJsonObject(); m_missing = false; QFile file(target); if (!file.exists()) { m_missing = true; return; } if (!file.open(QIODevice::ReadOnly)) { m_warnings.append( QObject::tr("Cannot read %1: %2").arg(target, file.errorString())); return; } QJsonParseError error{}; const QJsonDocument document = QJsonDocument::fromJson(file.readAll(), &error); if (error.error != QJsonParseError::NoError || !document.isObject()) { m_warnings.append(QObject::tr("Cannot read %1: %2") .arg(target, error.errorString())); return; } const QJsonObject root = document.object(); const int version = root.value(QStringLiteral("version")) .toInt(kFormatVersion); if (version != kFormatVersion) { m_warnings.append( QObject::tr("%1 uses format version %2, newer than this version " "understands (%3); refusing to guess") .arg(target).arg(version).arg(kFormatVersion)); return; } for (auto it = root.begin(); it != root.end(); ++it) { if (it.key() != QStringLiteral("version") && it.key() != QStringLiteral("rules")) { m_unknown.insert(it.key(), it.value()); } } // An id is a handle: a UI selects on it and a diff tracks it. static const QRegularExpression idPattern( QStringLiteral("^[a-z0-9][a-z0-9-]*$")); QStringList seen; const QJsonArray array = root.value(QStringLiteral("rules")).toArray(); for (int index = 0; index < array.size(); ++index) { const QJsonObject object = array.at(index).toObject(); const QString where = QObject::tr("rule #%1").arg(index + 1); TagRule rule; rule.id = object.value(QStringLiteral("id")).toString(); if (!idPattern.match(rule.id).hasMatch()) { m_warnings.append( QObject::tr("%1: id '%2' is missing or not lowercase letters, " "digits and dashes; dropped") .arg(where, rule.id)); continue; } if (seen.contains(rule.id)) { m_warnings.append(QObject::tr("Rule '%1': duplicate id; keeping " "the first").arg(rule.id)); continue; } rule.query = object.value(QStringLiteral("query")).toString().trimmed(); if (rule.query.isEmpty()) { m_warnings.append( QObject::tr("Rule '%1': no query; dropped").arg(rule.id)); continue; } rule.add = stringsOf(object.value(QStringLiteral("add"))); rule.remove = stringsOf(object.value(QStringLiteral("remove"))); if (rule.add.isEmpty() && rule.remove.isEmpty()) { m_warnings.append(QObject::tr("Rule '%1': adds and removes " "nothing; dropped").arg(rule.id)); continue; } rule.stage = object.value(QStringLiteral("stage")).toInt(kDefaultStage); rule.enabled = object.value(QStringLiteral("enabled")).toBool(true); rule.note = object.value(QStringLiteral("note")).toString(); for (auto it = object.begin(); it != object.end(); ++it) { if (!isKnownKey(it.key())) rule.unknown.insert(it.key(), it.value()); } seen.append(rule.id); m_rules.append(rule); } } bool TagRules::save(const QString &path) const { const QString target = path.isEmpty() ? defaultPath() : path; QDir().mkpath(QFileInfo(target).absolutePath()); QJsonArray array; for (const TagRule &rule : m_rules) { QJsonObject object; object.insert(QStringLiteral("id"), rule.id); object.insert(QStringLiteral("stage"), rule.stage); object.insert(QStringLiteral("enabled"), rule.enabled); object.insert(QStringLiteral("add"), QJsonArray::fromStringList(rule.add)); object.insert(QStringLiteral("remove"), QJsonArray::fromStringList(rule.remove)); object.insert(QStringLiteral("query"), rule.query); object.insert(QStringLiteral("note"), rule.note); for (auto it = rule.unknown.begin(); it != rule.unknown.end(); ++it) object.insert(it.key(), it.value()); array.append(object); } QJsonObject root = m_unknown; root.insert(QStringLiteral("version"), kFormatVersion); root.insert(QStringLiteral("rules"), array); // QSaveFile writes a temporary and renames on commit, which is the same // atomicity mailrules.py gets from os.replace. The hook must never read a // half-written file. QSaveFile file(target); if (!file.open(QIODevice::WriteOnly | QIODevice::Truncate)) return false; file.write(QJsonDocument(root).toJson(QJsonDocument::Indented)); return file.commit(); } QList TagRules::ordered() const { QList out; for (const TagRule &rule : m_rules) { if (rule.enabled) out.append(rule); } // stable_sort, not sort: ties must keep file order, which is the tie-break // the format promises and what lets a user sequence rules within a stage. std::stable_sort(out.begin(), out.end(), [](const TagRule &a, const TagRule &b) { return a.stage < b.stage; }); return out; } ``` Add `tagrules.cpp` to the `qtmaildir_lib` source list in `src/CMakeLists.txt`. Add the include `#include ` is not needed; `QObject::tr` comes in via `QJsonObject`'s transitive includes in Qt 6, but add `#include ` and `#include ` if the build reports them missing. - [ ] **Step 5: Run the tests to verify they pass** Run: `cmake --build build && ctest --test-dir build -R tagrules --output-on-failure` Expected: PASS, 8 test functions - [ ] **Step 6: Mutation-check the unknown-field guard** The neutrality guarantee is the one property with no visible symptom when broken, so prove the test detects its loss. In `src/tagrules.cpp`, temporarily comment out the unknown-field loop in `save()`: ```cpp // for (auto it = rule.unknown.begin(); it != rule.unknown.end(); ++it) // object.insert(it.key(), it.value()); ``` Run: `cmake --build build && ctest --test-dir build -R tagrules --output-on-failure` Expected: FAIL on `unknownFieldsSurviveASave` Restore the loop (copy the file to the scratchpad first and `cp` it back; `git checkout` would discard the whole implementation, which has already cost this project real work). - [ ] **Step 7: Commit** ```bash git add src/tagrules.h src/tagrules.cpp src/CMakeLists.txt \ tests/test_tagrules.cpp tests/CMakeLists.txt git commit -S -m "feat(rules): read and write the shared rule store The same ~/.config/mailrules/rules.json mailctl reads, parsed here with QJsonDocument and written atomically with QSaveFile. Fields this version does not understand round-trip untouched, which is what keeps the format neutral between the two tools. Mutation-checked: removing the unknown-field write fails unknownFieldsSurviveASave." ``` --- ## Task 11: The worker counts messages, not threads **Files:** - Modify: `src/notmuchworker.h`, `src/notmuchworker.cpp` - Modify: `tests/test_notmuchworker.cpp` - [ ] **Step 1: Write the failing test** `requestCounts` already exists and counts THREADS (`src/notmuchworker.cpp:637`, `notmuch_query_count_threads`). A tagging rule tags messages, and a thread count misreports any rule matching a few replies inside large threads. Add a message-counting slot beside it. Add to `tests/test_notmuchworker.cpp`, following the fixture pattern already in that file (locate the existing `private slots:` block and add the declaration there): ```cpp void messageCountsCountMessagesNotThreads(); void messageCountsReportAnInvalidQueryAsMinusOne(); ``` And the implementations, beside the other count tests: ```cpp void TestNotmuchWorker::messageCountsCountMessagesNotThreads() { // The fixture is 6 messages in 5 threads: thread A carries a reply, every // other thread is a single message. That difference is the whole reason // this slot exists beside requestCounts, and it is what the numbers below // assert. A rule that matched one reply of a 30-message thread would be // reported as 1 by a thread count, understating it by 29. NotmuchWorker worker(m_fixture.configPath()); QSignalSpy messages(&worker, &NotmuchWorker::messageCountsReady); QSignalSpy threads(&worker, &NotmuchWorker::countsReady); worker.requestMessageCounts({ QStringLiteral("*") }, 1); worker.requestCounts({ QStringLiteral("*") }, 1); QCOMPARE(messages.count(), 1); QCOMPARE(threads.count(), 1); const QVector messageCounts = messages.first().at(0).value>(); const QVector threadCounts = threads.first().at(0).value>(); QCOMPARE(messageCounts, (QVector{ 6 })); // The guard that makes this test mean something: if requestMessageCounts // were implemented with count_threads it would return 5 here and match // the thread count, and the assertion above would be the only thing that // caught it. QCOMPARE(threadCounts, (QVector{ 5 })); } void TestNotmuchWorker::messageCountsReportAnInvalidQueryAsMinusOne() { // Paired positionally with the caller's rules, so a dropped answer would // put a real number against the wrong rule. -1 says "this one failed". NotmuchWorker worker(m_fixture.configPath()); QSignalSpy spy(&worker, &NotmuchWorker::messageCountsReady); worker.requestMessageCounts({ QStringLiteral("from:(((("), QStringLiteral("*") }, 1); const QVector counts = spy.first().at(0).value>(); QCOMPARE(counts.size(), 2); QCOMPARE(counts.at(0), -1); QCOMPARE(counts.at(1), 6); } ``` Declare both in the `private slots:` block. The fixture builds 6 messages in 5 threads in `initTestCase()` (`tests/test_notmuchworker.cpp:95`); read it before writing the numbers, and if a message has been added since this plan was written, use the real counts rather than these. Use whatever accessor the existing tests use to reach the fixture's notmuch config, matching the surrounding tests rather than the `m_fixture.configPath()` written here. - [ ] **Step 2: Run the test to verify it fails** Run: `cmake --build build && ctest --test-dir build -R notmuchworker --output-on-failure` Expected: build FAILS with `no member named 'requestMessageCounts' in 'NotmuchWorker'` - [ ] **Step 3: Write the implementation** In `src/notmuchworker.h`, beside `requestCounts` in `public slots:`: ```cpp /// Message counts for each query, positionally paired with the input. /// /// Beside requestCounts rather than replacing it: that one counts THREADS, /// which is right for the placeholder pane because a click there produces /// thread rows. A tagging rule tags messages, so a thread count would /// understate any rule matching part of a large thread. void requestMessageCounts(const QStringList &queries, quint64 generation); ``` And in `signals:`: ```cpp void messageCountsReady(const QVector &counts, quint64 generation); ``` In `src/notmuchworker.cpp`, beside `requestCounts`: ```cpp void NotmuchWorker::requestMessageCounts(const QStringList &queries, quint64 generation) { if (!openReadOnly()) return; QVector counts; counts.reserve(queries.size()); for (const QString &query : queries) { NmQuery nmQuery(notmuch_query_create(m_db, query.toUtf8().constData())); unsigned int count = 0; // -1 rather than a skipped entry, matching requestCounts: the caller // pairs these with its own rules positionally, so a dropped answer // would put a real number against the wrong rule. if (!nmQuery || notmuch_query_count_messages(nmQuery.get(), &count) != NOTMUCH_STATUS_SUCCESS) { counts.append(-1); continue; } counts.append(static_cast(count)); } emit messageCountsReady(counts, generation); } ``` - [ ] **Step 4: Run the test to verify it passes** Run: `cmake --build build && ctest --test-dir build -R notmuchworker --output-on-failure` Expected: PASS - [ ] **Step 5: Commit** ```bash git add src/notmuchworker.h src/notmuchworker.cpp tests/test_notmuchworker.cpp git commit -S -m "feat(worker): count messages as well as threads requestCounts counts threads, which is right for the placeholder pane. A tagging rule tags messages, so a dry run over rules needs the message count or it understates every rule that matches part of a thread." ``` --- ## Task 12: The rules dialog **Files:** - Create: `src/tagrulesdialog.h`, `src/tagrulesdialog.cpp` - Modify: `src/CMakeLists.txt` - [ ] **Step 1: Write the dialog** Create `src/tagrulesdialog.h`: ```cpp /* * qtmaildir - a Qt6 mail client for notmuch-indexed Maildirs * Copyright (C) 2026 Danilo M. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License version 2 as * published by the Free Software Foundation. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */ #pragma once #include #include "tagrules.h" class QCheckBox; class QLabel; class QLineEdit; class QPlainTextEdit; class QPushButton; class QSpinBox; class QTreeWidget; class QTreeWidgetItem; /// Views and edits the shared auto-tagging rules. /// /// Does NOT apply rules to existing mail. The counts are shown so a rule can be /// judged before it runs, but the only thing that tags mail is the notmuch /// post-new hook. Backfill is deliberately out of this version: a rule that is /// safe against arrivals is not automatically safe unscoped, and the /// confirmation story for a bulk write does not exist yet. class TagRulesDialog : public QDialog { Q_OBJECT public: explicit TagRulesDialog(QWidget *parent = nullptr); /// The queries whose message counts the dialog wants, in the order its /// rows appear. MainWindow hands these to the worker; the dialog never /// touches the database itself, because NotmuchWorker owns the only /// handle and notmuch permits one per process. QStringList countQueries() const; signals: /// Asks the owner to run countQueries() through the worker. void countsRequested(); public slots: /// Corpus counts, positionally paired with countQueries(). void setCounts(const QVector &counts); private slots: void onSelectionChanged(); void onAddRule(); void onCopyRule(); void onDeleteRule(); void applyEditsToCurrentRule(); void onSave(); private: void reloadList(); void showWarnings(); int currentIndex() const; TagRules m_rules; QList m_working; ///< Edited copy; written only on Save. QTreeWidget *m_list = nullptr; QLineEdit *m_id = nullptr; QLineEdit *m_add = nullptr; QLineEdit *m_remove = nullptr; QLineEdit *m_query = nullptr; QPlainTextEdit *m_note = nullptr; QSpinBox *m_stage = nullptr; QCheckBox *m_enabled = nullptr; QLabel *m_warningLabel = nullptr; QPushButton *m_saveButton = nullptr; }; ``` Create `src/tagrulesdialog.cpp` with the standard GPL header, then: ```cpp #include "tagrulesdialog.h" #include #include #include #include #include #include #include #include #include #include #include #include #include namespace { /// Columns of the rule list. enum Column { ColumnEnabled = 0, ColumnStage, ColumnId, ColumnTags, ColumnCount }; QStringList splitTags(const QString &text) { QStringList out; for (const QString &part : text.split(QLatin1Char(','))) { const QString trimmed = part.trimmed(); if (!trimmed.isEmpty()) out.append(trimmed); } return out; } } // namespace TagRulesDialog::TagRulesDialog(QWidget *parent) : QDialog(parent) { setWindowTitle(tr("Tagging rules")); resize(760, 520); m_rules.load(); m_working = m_rules.rules(); auto *layout = new QVBoxLayout(this); auto *intro = new QLabel( tr("Rules tag mail as it arrives, applied by the notmuch post-new " "hook. Editing them here changes what the next sync does; it does " "not retag mail you already have."), this); intro->setWordWrap(true); layout->addWidget(intro); m_warningLabel = new QLabel(this); m_warningLabel->setWordWrap(true); m_warningLabel->setVisible(false); layout->addWidget(m_warningLabel); m_list = new QTreeWidget(this); m_list->setColumnCount(ColumnCount + 1); m_list->setHeaderLabels({ tr("On"), tr("Stage"), tr("Rule"), tr("Tags"), tr("Matches") }); m_list->setRootIsDecorated(false); m_list->setUniformRowHeights(true); layout->addWidget(m_list, 1); auto *form = new QFormLayout; m_id = new QLineEdit(this); m_stage = new QSpinBox(this); m_stage->setRange(0, 999); m_enabled = new QCheckBox(tr("Applied on every sync"), this); m_add = new QLineEdit(this); m_add->setPlaceholderText(tr("comma separated")); m_remove = new QLineEdit(this); m_remove->setPlaceholderText(tr("comma separated")); m_query = new QLineEdit(this); // Query syntax is wire format, never translated. Only the prose is. m_query->setPlaceholderText(QStringLiteral("from:sender@example.com")); m_note = new QPlainTextEdit(this); m_note->setMaximumHeight(70); form->addRow(tr("Name"), m_id); form->addRow(tr("Stage"), m_stage); form->addRow(QString(), m_enabled); form->addRow(tr("Add tags"), m_add); form->addRow(tr("Remove tags"), m_remove); form->addRow(tr("Query"), m_query); form->addRow(tr("Note"), m_note); layout->addLayout(form); auto *buttons = new QHBoxLayout; auto *addButton = new QPushButton(tr("&New"), this); auto *copyButton = new QPushButton(tr("&Copy"), this); auto *deleteButton = new QPushButton(tr("&Delete"), this); auto *refreshButton = new QPushButton(tr("Count &matches"), this); buttons->addWidget(addButton); buttons->addWidget(copyButton); buttons->addWidget(deleteButton); buttons->addStretch(); buttons->addWidget(refreshButton); layout->addLayout(buttons); auto *box = new QDialogButtonBox(QDialogButtonBox::Save | QDialogButtonBox::Cancel, this); m_saveButton = box->button(QDialogButtonBox::Save); layout->addWidget(box); connect(m_list, &QTreeWidget::currentItemChanged, this, &TagRulesDialog::onSelectionChanged); connect(addButton, &QPushButton::clicked, this, &TagRulesDialog::onAddRule); connect(copyButton, &QPushButton::clicked, this, &TagRulesDialog::onCopyRule); connect(deleteButton, &QPushButton::clicked, this, &TagRulesDialog::onDeleteRule); connect(refreshButton, &QPushButton::clicked, this, &TagRulesDialog::countsRequested); connect(box, &QDialogButtonBox::accepted, this, &TagRulesDialog::onSave); connect(box, &QDialogButtonBox::rejected, this, &QDialog::reject); // Edits land on the working copy as they are made, so switching rows does // not silently discard what was typed. connect(m_id, &QLineEdit::editingFinished, this, &TagRulesDialog::applyEditsToCurrentRule); connect(m_add, &QLineEdit::editingFinished, this, &TagRulesDialog::applyEditsToCurrentRule); connect(m_remove, &QLineEdit::editingFinished, this, &TagRulesDialog::applyEditsToCurrentRule); connect(m_query, &QLineEdit::editingFinished, this, &TagRulesDialog::applyEditsToCurrentRule); connect(m_stage, &QSpinBox::editingFinished, this, &TagRulesDialog::applyEditsToCurrentRule); connect(m_enabled, &QCheckBox::toggled, this, &TagRulesDialog::applyEditsToCurrentRule); reloadList(); showWarnings(); } void TagRulesDialog::showWarnings() { const QStringList warnings = m_rules.warnings(); if (warnings.isEmpty()) { m_warningLabel->setVisible(false); return; } m_warningLabel->setText( tr("%n rule(s) could not be read and were skipped: %1", "", warnings.size()).arg(warnings.join(QStringLiteral("; ")))); m_warningLabel->setVisible(true); } void TagRulesDialog::reloadList() { m_list->clear(); for (const TagRule &rule : m_working) { auto *item = new QTreeWidgetItem(m_list); item->setCheckState(ColumnEnabled, rule.enabled ? Qt::Checked : Qt::Unchecked); item->setText(ColumnStage, QString::number(rule.stage)); item->setText(ColumnId, rule.id); QStringList tags; for (const QString &tag : rule.add) tags.append(QStringLiteral("+") + tag); for (const QString &tag : rule.remove) tags.append(QStringLiteral("-") + tag); item->setText(ColumnTags, tags.join(QStringLiteral(" "))); } m_list->resizeColumnToContents(ColumnEnabled); m_list->resizeColumnToContents(ColumnStage); if (!m_working.isEmpty()) m_list->setCurrentItem(m_list->topLevelItem(0)); } int TagRulesDialog::currentIndex() const { return m_list->currentItem() ? m_list->indexOfTopLevelItem(m_list->currentItem()) : -1; } void TagRulesDialog::onSelectionChanged() { const int index = currentIndex(); if (index < 0 || index >= m_working.size()) return; const TagRule &rule = m_working.at(index); m_id->setText(rule.id); m_stage->setValue(rule.stage); m_enabled->setChecked(rule.enabled); m_add->setText(rule.add.join(QStringLiteral(", "))); m_remove->setText(rule.remove.join(QStringLiteral(", "))); m_query->setText(rule.query); m_note->setPlainText(rule.note); } void TagRulesDialog::applyEditsToCurrentRule() { const int index = currentIndex(); if (index < 0 || index >= m_working.size()) return; TagRule &rule = m_working[index]; rule.id = m_id->text().trimmed(); rule.stage = m_stage->value(); rule.enabled = m_enabled->isChecked(); rule.add = splitTags(m_add->text()); rule.remove = splitTags(m_remove->text()); rule.query = m_query->text().trimmed(); rule.note = m_note->toPlainText(); QTreeWidgetItem *item = m_list->topLevelItem(index); item->setCheckState(ColumnEnabled, rule.enabled ? Qt::Checked : Qt::Unchecked); item->setText(ColumnStage, QString::number(rule.stage)); item->setText(ColumnId, rule.id); QStringList tags; for (const QString &tag : rule.add) tags.append(QStringLiteral("+") + tag); for (const QString &tag : rule.remove) tags.append(QStringLiteral("-") + tag); item->setText(ColumnTags, tags.join(QStringLiteral(" "))); } void TagRulesDialog::onAddRule() { TagRule rule; rule.id = QStringLiteral("new-rule"); rule.query = QStringLiteral("from:sender@example.com"); rule.add = { QStringLiteral("tag") }; m_working.append(rule); reloadList(); m_list->setCurrentItem(m_list->topLevelItem(m_working.size() - 1)); } void TagRulesDialog::onCopyRule() { const int index = currentIndex(); if (index < 0 || index >= m_working.size()) return; TagRule copy = m_working.at(index); copy.id += QStringLiteral("-copy"); m_working.insert(index + 1, copy); reloadList(); m_list->setCurrentItem(m_list->topLevelItem(index + 1)); } void TagRulesDialog::onDeleteRule() { const int index = currentIndex(); if (index < 0 || index >= m_working.size()) return; m_working.removeAt(index); reloadList(); } QStringList TagRulesDialog::countQueries() const { QStringList queries; for (const TagRule &rule : m_working) queries.append(rule.query); return queries; } void TagRulesDialog::setCounts(const QVector &counts) { for (int i = 0; i < counts.size() && i < m_list->topLevelItemCount(); ++i) { // -1 is the worker's "this query could not be run", which for a rule // means the query is malformed. Saying so beats showing a number. m_list->topLevelItem(i)->setText( ColumnCount, counts.at(i) < 0 ? tr("invalid") : QString::number(counts.at(i))); } m_list->resizeColumnToContents(ColumnCount); } void TagRulesDialog::onSave() { applyEditsToCurrentRule(); m_rules.setRules(m_working); if (!m_rules.save()) { QMessageBox::warning(this, tr("Tagging rules"), tr("Could not write %1.") .arg(TagRules::defaultPath())); return; } accept(); } ``` Add both files to the `qtmaildir_lib` source list in `src/CMakeLists.txt`. - [ ] **Step 2: Build** Run: `cmake --build build` Expected: builds clean - [ ] **Step 3: Commit** ```bash git add src/tagrulesdialog.h src/tagrulesdialog.cpp src/CMakeLists.txt git commit -S -m "feat(rules): a dialog to view and edit the tagging rules Edits land on a working copy and reach the file only on Save. The dialog never opens a notmuch database of its own: it publishes the queries it wants counted and MainWindow runs them through the worker, because the worker owns the only handle." ``` --- ## Task 13: Wire the dialog into MainWindow **Files:** - Modify: `src/mainwindow.h`, `src/mainwindow.cpp` - [ ] **Step 1: Add the action and the counting round-trip** In `src/mainwindow.h`, add to the private slots: ```cpp void showTagRulesDialog(); void onRuleCountsReady(const QVector &counts, quint64 generation); ``` And to the members: ```cpp /// The open rules dialog, or null. Held so a counts reply can reach it, /// and cleared when it closes: a reply that arrives after the dialog is /// gone must find nothing rather than a dangling pointer. QPointer m_tagRulesDialog; quint64 m_ruleCountGeneration = 0; ``` Add `#include ` and a forward declaration `class TagRulesDialog;`. In `src/mainwindow.cpp`, add `#include "tagrulesdialog.h"`. Register the action beside the other `addAction` calls in `registerActions()`: ```cpp addAction(QStringLiteral("tag_rules"), tr("Tagging &rules..."), [this] { showTagRulesDialog(); }); ``` Add it to the Mail menu beside the other entries in `buildMenus()`: ```cpp messageMenu->addAction(m_actions.value(QStringLiteral("tag_rules"))); ``` Add the implementations: ```cpp void MainWindow::showTagRulesDialog() { // One dialog. A second would edit a stale copy and the last Save would // silently win, which is the lost-edit case the atomic write cannot help // with because both writers are this process. if (m_tagRulesDialog) { m_tagRulesDialog->raise(); m_tagRulesDialog->activateWindow(); return; } auto *dialog = new TagRulesDialog(this); dialog->setAttribute(Qt::WA_DeleteOnClose); m_tagRulesDialog = dialog; connect(dialog, &TagRulesDialog::countsRequested, this, [this, dialog] { m_ruleCountGeneration = ++m_generation; QMetaObject::invokeMethod( m_worker, "requestMessageCounts", Qt::QueuedConnection, Q_ARG(QStringList, dialog->countQueries()), Q_ARG(quint64, m_ruleCountGeneration)); }); dialog->show(); } void MainWindow::onRuleCountsReady(const QVector &counts, quint64 generation) { // Stale reply, or the dialog closed while the count was in flight. Both // are ordinary: counting every rule against a cold index takes seconds // (item 74), which is long enough for the user to close the dialog. if (generation != m_ruleCountGeneration || !m_tagRulesDialog) return; m_tagRulesDialog->setCounts(counts); } ``` Connect the worker signal in `wireWorker()`: ```cpp connect(m_worker, &NotmuchWorker::messageCountsReady, this, &MainWindow::onRuleCountsReady); ``` - [ ] **Step 2: Build and run the suite** Run: `cmake --build build && ctest --test-dir build --output-on-failure` Expected: PASS, 19/19 (18 existing plus `tagrules`) - [ ] **Step 3: Hand-test the dialog** Run: `./build/src/qtmaildir` Verify by looking, not by inference (this project's own rule: a geometry probe cannot see what it was not built to look for): 1. Mail > Tagging rules opens the dialog and lists the rules from `~/.config/mailrules/rules.json`. 2. "Count matches" fills the Matches column with numbers that agree with `mailctl rules dry-run`. 3. Editing a rule, saving, and reopening shows the edit. 4. `mailctl rules list` shows the same edit, proving both parsers agree. - [ ] **Step 4: Commit** ```bash git add src/mainwindow.h src/mainwindow.cpp git commit -S -m "feat(rules): open the tagging rules from the Mail menu Counts are generation-stamped and dropped when stale or when the dialog has closed: counting every rule against a cold index takes seconds, so an in-flight reply outliving its dialog is ordinary rather than rare." ``` --- ## Task 14: Migrate the real rules **Files:** - Read: `/data/Mail/.notmuch/hooks/post-new` - Create: `~/.config/mailrules/rules.json` - Create: `/.notmuch/hooks/post-new.new` Nothing in this task is committed to either repository. The real hook contains account names and sender addresses, which must not reach a commit. - [ ] **Step 1: Convert the rules** Read `/data/Mail/.notmuch/hooks/post-new` and write `~/.config/mailrules/rules.json` with one rule per `notmuch tag` line: - `id` derived from the tag, lowercased, `/` and `.` replaced with `-` (`+notify/github` becomes `notify-github`). - `stage` 10 for the five account rules, 50 for every topic rule. This preserves the ordering the current file gets from line order, and the account rules must run first because nothing depends on them but they are the coarsest. - `add` from the `+tag` arguments. - `query` from the part after `tag:new and`, with the outer parentheses removed if present. **Do not include `tag:new`**: the hook adds it. - `note` from the comment block above the rule, joined into one paragraph. This is the whole point of the migration; a rule that loses its "deliberately excludes PayPal receipts, and here is why" comment is a rule someone will break later. Do not convert the final `notmuch tag -new -- tag:new` line. It is the hook's own cleanup and is hardcoded there. - [ ] **Step 2: Prove equivalence before switching anything** For each converted rule, compare what the old and new constructions match across the whole corpus: ```bash # For one rule, with OLD the query as written in the current hook and # NEW the stored query: notmuch count -- 'OLD' notmuch count -- 'tag:new and (NEW)' ``` Since nothing carries `tag:new` between syncs, both scoped counts read 0 and prove nothing on their own. Compare the UNSCOPED forms, which is what actually tests the conversion: ```bash notmuch count -- 'OLD_WITHOUT_TAG_NEW' notmuch count -- 'NEW' ``` Build the full table with `mailctl rules dry-run` on one side and a shell loop over the old queries on the other. **Every pair must match exactly.** A mismatch means the conversion changed the rule, most likely by dropping or adding parentheses around a disjunction. Save the table to a local file outside both repositories, for example `~/rules-migration-check.txt`. It names real senders and is not committed. - [ ] **Step 3: Stage the new hook** ```bash DB="$(notmuch config get database.path)" cp ../mailctl/post-new "$DB/.notmuch/hooks/post-new.new" cp ../mailctl/mailrules.py "$DB/.notmuch/hooks/mailrules.py" chmod +x "$DB/.notmuch/hooks/post-new.new" ``` The existing `post-new` is untouched and keeps running on every sync. - [ ] **Step 4: Dry-run the new hook against real arrivals** Wait for or trigger a sync so that some mail carries `tag:new`, then run the staged hook by hand and inspect what it did: ```bash notmuch count tag:new # how many arrived "$DB/.notmuch/hooks/post-new.new" notmuch count tag:new # 0 if it completed ``` Compare the tags applied against what the old hook would have applied. If anything is wrong, `tag:new` is already consumed, so re-tag by hand from the saved table rather than re-running. - [ ] **Step 5: Switch, once the user is satisfied** This is the user's decision and their command to run: ```bash DB="$(notmuch config get database.path)" mv "$DB/.notmuch/hooks/post-new" "$DB/.notmuch/hooks/post-new.shell-backup" mv "$DB/.notmuch/hooks/post-new.new" "$DB/.notmuch/hooks/post-new" ``` Keep the backup. It is the only copy of the original comments outside the converted `note` fields. --- ## Task 15: Close out the backlog item **Files:** - Modify: `docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md` - Modify: `CHANGELOG.md` - [ ] **Step 1: Update the status table** Change item 44's row to: ```markdown | 44 | No way to manage the filters applied at sync time | workflow | M | **done** ; see `specs/2026-08-12-tagging-rules-design.md`. Spans this repo and `mailctl` | ``` - [ ] **Step 2: Add an Outcome section** Under `## 44.`, after the existing prose: ```markdown ### Outcome (done ) The rules moved from a hand-written shell hook to `~/.config/mailrules/rules.json`, read by both qtmaildir and mailctl. The `post-new` hook and the shared `mailrules.py` live in the mailctl repository; qtmaildir has `TagRules` and a management dialog reached from the Mail menu. Two things worth keeping. The parenthesisation of a rule's own query is load-bearing: `tag:new and a or b` binds as `(tag:new and a) or b`, so a rule that is a disjunction of senders would escape its scope and match the whole corpus. And the hook must not consume `tag:new` when the rules failed to load, because clearing the marker while the rules did not run orphans that mail permanently and invisibly. Backfill remains out of scope; see the spec's "Out of scope" section for what it needs first. ``` - [ ] **Step 3: Add the changelog entry** Under `## [Unreleased]`, in `### Added`: ```markdown - Tagging rules are now managed from Mail > Tagging rules, reading and writing a shared store at `~/.config/mailrules/rules.json`. Each rule shows how much mail it matches, so a rule can be judged before the next sync applies it. The rules are applied by the notmuch `post-new` hook, which now reads that same file; the companion `mailctl` tool reads it too. ``` Add an `### Upgrading` note, since this requires the user to install a hook: ```markdown ### Upgrading The tagging rules moved out of the notmuch `post-new` hook into `~/.config/mailrules/rules.json`. Install the new hook and its library from the `mailctl` project (`post-new` and `mailrules.py` into `/.notmuch/hooks/`), and keep a backup of the previous shell hook until a sync has run with the new one. ``` - [ ] **Step 4: Commit** ```bash git add docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md CHANGELOG.md git commit -S -m "docs(backlog): record item 44 as done" ``` --- ## Self-review **Spec coverage:** | Spec section | Task | |---|---| | File location, `$XDG_CONFIG_HOME` | 1 (Python), 10 (C++) | | Field table, defaults | 1, 2, 10 | | Unknown-key preservation | 4, 10 | | `version` refusal | 2, 10 | | Scope belongs to the runner | 5 | | `-new` hardcoded, only on success | 6, 7 | | Parenthesisation | 5, 7 | | Runner in Python, in mailctl's repo | 6 | | Validation degrades, not fatal | 2, 10 | | Dry-run on the worker, generation-stamped | 11, 13 | | Two counts per rule | 9 (mailctl), 12 (dialog) | | Dialog: view/edit/create/delete/copy | 12 | | mailctl read-only `rules` subcommand | 8, 9 | | Atomic writes, no locking | 4, 10 | | Migration, equivalence proof, staged hook | 14 | | Backfill out of scope | Stated in 12's header comment and 15's outcome | | Testing across both repos | 1-5, 7, 10, 11 | **Placeholder scan:** none. Every code step carries the code; the one task without a unit test (6) says why and is covered end-to-end by 7. **Type consistency:** `mailrules.load/save/ordered/scoped_query/tag_arguments` and `Rule`/`Store` are used consistently in Tasks 1-9 and 14. `TagRules::load/save/rules/setRules/ordered/warnings/missing/defaultPath` and `TagRule` are consistent across 10, 12 and 13. `requestMessageCounts`/`messageCountsReady` match between 11, 12 and 13. `countQueries`/`setCounts`/`countsRequested` match between 12 and 13. **Known deviation from the spec**, stated at the top of this plan: the spec's `countRules` worker slot is implemented as a general `requestMessageCounts`, because `requestCounts` already existed and counts threads rather than messages.