diff options
Diffstat (limited to 'docs/superpowers/plans')
| -rw-r--r-- | docs/superpowers/plans/2026-11-16-rule-move.md | 987 |
1 files changed, 987 insertions, 0 deletions
diff --git a/docs/superpowers/plans/2026-11-16-rule-move.md b/docs/superpowers/plans/2026-11-16-rule-move.md new file mode 100644 index 0000000..4e43280 --- /dev/null +++ b/docs/superpowers/plans/2026-11-16-rule-move.md @@ -0,0 +1,987 @@ +# Rule move to spam or trash: 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:** A tagging rule can carry `"move": "spam" | "trash"`, and the `post-new` hook moves matching new mail into each message's own account's folder for that role. + +**Architecture:** One optional field in `rules.json`, known to both readers (`src/tagrules.cpp`, `assets/hooks/mailrules.py`). The hook gains a move step after the tag stages: rename into `<account>/<folder>/cur/` under a fresh name, one `notmuch new --no-hooks` to record the renames, then tag. The dialog gains a *Move to* combo. Spec: `docs/superpowers/specs/2026-11-16-rule-move-design.md`. + +**Tech Stack:** Python 3 stdlib (hook), Qt 6 / C++ (`TagRules`, `TagRulesDialog`), notmuch CLI. + +--- + +## Before anything: work in a worktree + +The live notmuch `database.hook_dir` SYMLINKS into this repo's `assets/hooks/`, +so an edit to `post-new` in the main checkout runs on the user's real mail at +the next sync, ten minutes away at most. Every task below happens in a +worktree, never in `~/Programming/GIT/qtmaildir` itself: + +```bash +cd ~/Programming/GIT/qtmaildir +git worktree add ../qtmaildir-rule-move -b rule-move +cd ../qtmaildir-rule-move +cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug && cmake --build build +``` + +All paths below are relative to that worktree. + +**No commits until the user's verdict.** The user's standing rule: hand the +change back and wait. Tasks end at "suite green", not at a commit. Task 7 is +the hand-over; the commit and merge come after the user says so. + +**Never run a test binary without `QT_QPA_PLATFORM=offscreen`.** + +--- + +### Task 1: `qtmaildirconf.role_folders()` + +**Files:** +- Modify: `assets/hooks/qtmaildirconf.py` (after `not_arrival_query`) +- Test: `assets/hooks/test_qtmaildirconf.py` + +- [ ] **Step 1: Write the failing tests** (before `def main():`) + +```python +def test_role_folders_pair_each_account_with_its_folder(): + with tempfile.TemporaryDirectory() as tmp: + path = write_config(tmp, + "[account.one]\nmaildir = acct-one\nspam = Spam\ntrash = Trash\n" + "[account.two]\nmaildir = acct-two\nspam = [Provider]/Spam\n") + assert qtmaildirconf.role_folders("spam", path) == [ + ("acct-one", "Spam"), ("acct-two", "[Provider]/Spam")] + # acct-two names no trash folder, so it contributes nothing rather + # than a guess the hook would then create on the server. + assert qtmaildirconf.role_folders("trash", path) == [ + ("acct-one", "Trash")] + + +def test_role_folders_need_a_maildir(): + with tempfile.TemporaryDirectory() as tmp: + path = write_config(tmp, "[account.one]\nspam = Spam\n") + assert qtmaildirconf.role_folders("spam", path) == [] +``` + +`write_config(tmp, text)` returns the path it wrote, and `main()` collects +every `test_` function. + +- [ ] **Step 2: Run, expect FAIL** (`AttributeError: ... role_folders`) + +Run: `cd assets/hooks && ./test_qtmaildirconf.py` + +- [ ] **Step 3: Implement** (append to `qtmaildirconf.py`) + +```python +# The folders a rule may MOVE mail into, by role. A rule names a role, never a +# folder: a folder name that does not exist is created by the move and reaches +# the server (item 103), and a role resolves per account, so one rule serves +# mail from every account. +MOVE_ROLES = ("spam", "trash") + + +def role_folders(role, path=None): + """Every account's (maildir, folder) pair for a move role. + + An account contributes nothing unless it names both its maildir and a + folder for the role. `spam` and `trash` are mandatory to the application, + which warns about a missing one; here a missing one just means that + account's mail is not moved. + """ + if path is None: + path = default_path() + + pairs = [] + for _key, section in _accounts(path): + maildir = section.get("maildir", "").strip() + folder = section.get(role, "").strip() + if maildir and folder: + pairs.append((maildir, folder)) + return pairs +``` + +- [ ] **Step 4: Run, expect all pass** + +Run: `cd assets/hooks && ./test_qtmaildirconf.py` + +--- + +### Task 2: `move` in `mailrules.py` + +**Files:** +- Modify: `assets/hooks/mailrules.py` (`KNOWN_KEYS`, `Rule`, `_rule_to_dict`, `_parse_rule`) +- Test: `assets/hooks/test_mailrules.py` + +- [ ] **Step 1: Write the failing tests** (before `def run_all():`) + +```python +def test_a_move_rule_loads_and_round_trips(): + with tempfile.TemporaryDirectory() as tmp: + path = write_rules(tmp, {"version": 1, "rules": [ + {"id": "junk", "query": "from:spammer@example.net", + "move": "spam"}]}) + store = mailrules.load(path) + assert store.warnings == [], store.warnings + # A move-only rule is a rule: it adds and removes nothing. + assert [r.id for r in store.rules] == ["junk"] + assert store.rules[0].move == "spam" + assert "move" not in store.rules[0].unknown + mailrules.save(store, path) + assert json.loads(path.read_text())["rules"][0]["move"] == "spam" + + +def test_a_rule_without_a_move_writes_no_move_key(): + """Absent stays absent. Writing `"move": ""` on every rule would rewrite + every file either reader saves, a diff nobody made.""" + with tempfile.TemporaryDirectory() as tmp: + path = write_rules(tmp, {"version": 1, "rules": [ + {"id": "x", "add": ["x"], "query": "from:a@example.com"}]}) + mailrules.save(mailrules.load(path), path) + assert "move" not in json.loads(path.read_text())["rules"][0] + + +def test_an_unknown_move_role_is_ignored_and_the_tags_still_apply(): + """The hook must never guess a destination, and must not lose the rule's + harmless tagging over it either.""" + with tempfile.TemporaryDirectory() as tmp: + path = write_rules(tmp, {"version": 1, "rules": [ + {"id": "odd", "add": ["x"], "query": "from:a@example.com", + "move": "Archive"}]}) + store = mailrules.load(path) + assert store.rules[0].move == "" + assert store.rules[0].add == ["x"] + assert len(store.warnings) == 1 and "Archive" in store.warnings[0] + + +def test_a_rule_whose_only_action_is_a_bad_move_is_dropped(): + with tempfile.TemporaryDirectory() as tmp: + path = write_rules(tmp, {"version": 1, "rules": [ + {"id": "odd", "query": "from:a@example.com", "move": "archive"}]}) + store = mailrules.load(path) + assert store.rules == [] + assert len(store.warnings) == 2, store.warnings +``` + +- [ ] **Step 2: Run, expect FAIL** + +Run: `cd assets/hooks && ./test_mailrules.py` + +- [ ] **Step 3: Implement** + +`KNOWN_KEYS`: + +```python +KNOWN_KEYS = {"id", "stage", "enabled", "add", "remove", "query", "note", + "move"} + +# What `move` may say. Mirrors qtmaildirconf.MOVE_ROLES and the C++ reader; +# see "Changing the rule format" in AGENTS.md. +MOVE_ROLES = ("spam", "trash") +``` + +`Rule` dataclass, after `remove`: + +```python + move: str = "" +``` + +`_rule_to_dict`, after building `out` and before `out.update(rule.unknown)`: + +```python + # Only when set, so a file with no moves is byte-identical after a save. + if rule.move: + out["move"] = rule.move +``` + +`_parse_rule`, replacing the `add`/`remove` emptiness check: + +```python + 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()] + + move = obj.get("move", "") + if move and move not in MOVE_ROLES: + warnings.append( + f"rule '{rule_id}': move '{move}' is not spam or trash; " + f"ignoring the move") + move = "" + + if not add and not remove and not move: + warnings.append( + f"rule '{rule_id}': adds, removes and moves nothing; dropped") + return None +``` + +and pass `move=move,` in the `Rule(...)` constructor. + +- [ ] **Step 4: Run, expect all pass** (including the pre-existing `test_a_bad_rule_is_dropped_and_the_rest_survive`, which checks ids, not the message text) + +Run: `cd assets/hooks && ./test_mailrules.py` + +--- + +### Task 3: the hook moves + +**Files:** +- Modify: `assets/hooks/post-new` +- Test: `assets/hooks/test_post_new.py` + +- [ ] **Step 1: Write the nesting test FIRST** (before `def run_all():`), with its fixture + +```python +import shutil # add to the imports at the top + + +def setup_move(tmp): + """Two accounts with spam folders, one also with a trash folder, and + mail from a spammer in both inboxes beside one real message. + + Account two names no trash folder on purpose: a trash rule must leave its + mail alone rather than invent one. + """ + root = Path(tmp) / "Mail" + for sub in ("acct-one/Inbox", "acct-one/Spam", "acct-one/Trash", + "acct-two/Inbox", "acct-two/[Provider]/Spam"): + for part in ("new", "cur", "tmp"): + (root / sub / part).mkdir(parents=True) + + make_message(root / "acct-one/Inbox", "junk-one", + "spammer@example.net", "buy now") + make_message(root / "acct-one/Inbox", "keep-one", + "friend@example.org", "hello") + make_message(root / "acct-two/Inbox", "junk-two", + "spammer@example.net", "buy again") + + config = Path(tmp) / "notmuch-config" + config.write_text( + f"[database]\npath={root}\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") + + conf = Path(env["XDG_CONFIG_HOME"]) / "qtmaildir" / "qtmaildir.conf" + conf.parent.mkdir(parents=True) + conf.write_text( + "[account.one]\nmaildir = acct-one\nspam = Spam\ntrash = Trash\n" + "[account.two]\nmaildir = acct-two\nspam = [Provider]/Spam\n") + + subprocess.run(["notmuch", "new"], env=env, capture_output=True, + check=True) + return env, root + + +SPAM_RULE = {"id": "junk", "query": "from:spammer@example.net", + "move": "spam"} + + +def names(folder): + return sorted(p.name for p in folder.iterdir()) + + +def test_the_hook_can_move_when_notmuch_new_itself_runs_it(): + """The design's one unverified assumption: that `notmuch new --no-hooks` + can run INSIDE post-new, because the outer `notmuch new` has released the + write lock by the time it calls the hook. Every other test runs the hook + directly and cannot see this. If it fails, stop: the fallback (moving from + mailsync.sh instead) is a design change for the user.""" + with tempfile.TemporaryDirectory() as tmp: + env, root = setup_move(tmp) + write_rules(env, [SPAM_RULE]) + + hooks = root / ".notmuch" / "hooks" + hooks.mkdir(parents=True) + os.symlink(HOOK, hooks / "post-new") + + make_message(root / "acct-one/Inbox", "junk-three", + "spammer@example.net", "and again") + result = subprocess.run(["notmuch", "new"], env=env, + capture_output=True, text=True) + assert result.returncode == 0, result.stderr + + assert count(env, "tag:spam") == 3, result.stderr + assert count(env, "tag:new") == 0 + assert names(root / "acct-one/Inbox/new") == ["keep-one"] +``` + +- [ ] **Step 2: Run it, expect FAIL on `tag:spam` (0, the hook does not move yet)** + +Run: `cd assets/hooks && ./test_post_new.py` + +The failure must be the `tag:spam` assertion. A non-zero `notmuch new` return +code here, before any hook change, means the fixture is wrong; fix that first. + +- [ ] **Step 3: Write the remaining hook tests** (same place) + +```python +def test_a_move_rule_puts_spam_in_each_accounts_own_spam_folder(): + with tempfile.TemporaryDirectory() as tmp: + env, root = setup_move(tmp) + write_rules(env, [SPAM_RULE]) + + result = subprocess.run([str(HOOK)], env=env, capture_output=True, + text=True) + assert result.returncode == 0, result.stderr + + # The files moved, each into ITS account's folder, under fresh names + # in cur/ carrying a flags suffix. + assert names(root / "acct-one/Inbox/new") == ["keep-one"] + assert names(root / "acct-two/Inbox/new") == [] + one = names(root / "acct-one/Spam/cur") + two = names(root / "acct-two/[Provider]/Spam/cur") + assert len(one) == 1 and len(two) == 1, (one, two) + assert one[0] != "junk-one" and one[0].endswith(":2,") + + # notmuch followed the rename and kept the message, not a fresh copy. + assert files(env, 'path:"acct-one/Spam/**"') == 1 + assert files(env, 'path:"acct-two/[Provider]/Spam/**"') == 1 + assert files(env, 'path:"acct-one/Inbox/**"') == 1 + + assert count(env, "tag:spam") == 2 + assert count(env, "tag:spam and tag:inbox") == 0 + # unread is the protection that reaches the server; it stays. + assert count(env, "tag:spam and tag:unread") == 2 + # Account-relative, the format Restore reads. + assert count(env, 'tag:"moved-from:Inbox"') == 2 + assert count(env, "tag:new") == 0 + assert count(env, "id:keep-one@example.org and tag:inbox") == 1 + + +def test_a_trash_rule_skips_an_account_with_no_trash_folder(): + with tempfile.TemporaryDirectory() as tmp: + env, root = setup_move(tmp) + write_rules(env, [dict(SPAM_RULE, move="trash")]) + + result = subprocess.run([str(HOOK)], env=env, capture_output=True, + text=True) + assert result.returncode == 0, result.stderr + + assert len(names(root / "acct-one/Trash/cur")) == 1 + assert count(env, "id:junk-one@example.org and tag:deleted") == 1 + assert count(env, "id:junk-one@example.org and tag:spam") == 0 + + assert names(root / "acct-two/Inbox/new") == ["junk-two"] + assert count(env, "id:junk-two@example.org and tag:inbox") == 1 + assert count(env, "id:junk-two@example.org and tag:deleted") == 0 + assert "not moved" in result.stderr + + +def test_the_first_move_rule_in_stage_order_wins(): + with tempfile.TemporaryDirectory() as tmp: + env, root = setup_move(tmp) + write_rules(env, [ + dict(SPAM_RULE, id="late", stage=50), + dict(SPAM_RULE, id="early", stage=10, move="trash"), + ]) + + result = subprocess.run([str(HOOK)], env=env, capture_output=True, + text=True) + assert result.returncode == 0, result.stderr + + assert len(names(root / "acct-one/Trash/cur")) == 1 + assert names(root / "acct-one/Spam/cur") == [] + assert "claimed" in result.stderr + + +def test_a_message_with_two_files_is_not_moved(): + """Item 166's shape: one Message-ID, a file in each account. One message + cannot carry two origins, so it is left where it is and logged.""" + with tempfile.TemporaryDirectory() as tmp: + env, root = setup_move(tmp) + shutil.copy(root / "acct-one/Inbox/new/junk-one", + root / "acct-two/Inbox/new/junk-one-copy") + subprocess.run(["notmuch", "new"], env=env, capture_output=True, + check=True) + write_rules(env, [SPAM_RULE]) + + result = subprocess.run([str(HOOK)], env=env, capture_output=True, + text=True) + assert result.returncode == 0, result.stderr + + assert "junk-one" in names(root / "acct-one/Inbox/new") + assert "junk-one-copy" in names(root / "acct-two/Inbox/new") + assert count(env, "id:junk-one@example.org and tag:spam") == 0 + assert "2 files" in result.stderr + + +def test_a_file_already_in_the_spam_folder_is_tagged_not_renamed(): + """Mail a provider filed itself, and the retry after a run whose rename + succeeded and whose tagging failed. Tagged, with no origin to record.""" + with tempfile.TemporaryDirectory() as tmp: + env, root = setup_move(tmp) + make_message(root / "acct-one/Spam", "already", + "spammer@example.net", "filed by the provider") + subprocess.run(["notmuch", "new"], env=env, capture_output=True, + check=True) + write_rules(env, [SPAM_RULE]) + + result = subprocess.run([str(HOOK)], env=env, capture_output=True, + text=True) + assert result.returncode == 0, result.stderr + + assert names(root / "acct-one/Spam/new") == ["already"] + assert count(env, "id:already@example.org and tag:spam") == 1 + assert count(env, "id:already@example.org and tag:inbox") == 0 + tags = subprocess.run( + ["notmuch", "search", "--output=tags", "id:already@example.org"], + env=env, capture_output=True, text=True, check=True).stdout + assert "moved-from:" not in tags, tags + + +def test_a_rule_skipped_for_a_protected_removal_moves_nothing(): + with tempfile.TemporaryDirectory() as tmp: + env, root = setup_move(tmp) + write_rules(env, [dict(SPAM_RULE, remove=["unread"])]) + + result = subprocess.run([str(HOOK)], env=env, capture_output=True, + text=True) + assert result.returncode == 0, result.stderr + assert names(root / "acct-one/Spam/cur") == [] +``` + +- [ ] **Step 4: Run, expect every new test to FAIL** + +Run: `cd assets/hooks && ./test_post_new.py` + +`run_all()` stops at the first failure. Comment out its `fn()` loop temporarily +only if needed to see each one; restore it before moving on. + +- [ ] **Step 5: Implement in `post-new`** + +Imports, beside `import subprocess`: + +```python +import itertools +import os +import socket +import time +``` + +After `run_tag()`: + +```python +_counter = itertools.count(1) + + +def fresh_name(old_name): + """A fresh, unique Maildir filename keeping `old_name`'s flags suffix. + + Port of MaildirName::fresh() in the application, and for its reason: the + `,U=<n>` infix mbsync writes is meaningful only within one folder, and + carrying it across a folder boundary produced `Maildir error: duplicate + UID` on real mail (item 162). A file coming from new/ has no `:2,` yet; + it gets an empty one, since it is going into cur/. + """ + sep = old_name.find(":2,") + info = old_name[sep:] if sep >= 0 else ":2," + host = (socket.gethostname() or "localhost").replace("/", "_") \ + .replace(":", "_") + now = time.time() + return (f"{int(now)}.M{int(now * 1000) % 1000}P{os.getpid()}" + f"Q{next(_counter)}.{host}{info}") + + +def account_of(path, root, pairs): + """The (maildir, folder) pair whose account holds `path`, or None. + + Longest maildir wins, so an account nested inside another's directory + resolves to itself. Compared as paths, never with startswith. + """ + best = None + for maildir, folder in pairs: + if _within(path, root / maildir) and ( + best is None or len(maildir) > len(best[0])): + best = (maildir, folder) + return best + + +def origin_of(path, root, maildir): + """The folder `path` sits in, relative to its ACCOUNT, without cur/new. + + The format MainWindow::originTagFor() writes and Restore reads: + `acct/Inbox/new/x` is `Inbox`. + """ + parts = path.parent.relative_to(root / maildir).parts + if parts and parts[-1] in ("cur", "new"): + parts = parts[:-1] + return "/".join(parts) + + +def apply_moves(rules): + """Move what each move rule matches into its account's role folder. + + True when done, including when there was nothing to do. False when a + notmuch step failed, so the caller leaves tag:new in place. A message + that cannot be moved (several files, no account, no folder for the role, + a failed rename) is logged and left where it is; that is not a failure. + """ + claimed = {} + for rule in rules: + if not rule.move: + continue + ids = search(mailrules.scoped_query(rule, SCOPE), "messages") + if ids is None: + return False + for message_id in ids: + if message_id in claimed: + log(f"rule '{rule.id}': {message_id} already claimed by " + f"rule '{claimed[message_id].id}'") + continue + claimed[message_id] = rule + + if not claimed: + return True + + root = mail_root() + if root is None: + log("no mail root; moving nothing") + return False + + pairs = {role: qtmaildirconf.role_folders(role) + for role in qtmaildirconf.MOVE_ROLES} + + to_tag = [] + renamed = False + for message_id, rule in claimed.items(): + paths = search(f"id:{_quote(message_id)}", "files") + if paths is None: + return False + if len(paths) != 1: + log(f"rule '{rule.id}': {message_id} has {len(paths)} files; " + f"not moved") + continue + + source = Path(paths[0]) + account = account_of(source, root, pairs[rule.move]) + if account is None: + log(f"rule '{rule.id}': {message_id} is in no account with a " + f"{rule.move} folder; not moved") + continue + + maildir, folder = account + target = root / maildir / folder + if _within(source, target): + to_tag.append((message_id, rule.move, "")) + continue + + # The configured folder must already exist. Creating it is how a + # mistyped name reaches the server (item 103); cur/ inside a real + # folder is safe to create. + if not target.is_dir(): + log(f"rule '{rule.id}': {target} does not exist; not moved") + continue + + origin = origin_of(source, root, maildir) + try: + (target / "cur").mkdir(exist_ok=True) + os.rename(source, target / "cur" / fresh_name(source.name)) + except OSError as exc: + log(f"rule '{rule.id}': cannot move {message_id}: {exc}") + continue + renamed = True + to_tag.append((message_id, rule.move, origin)) + + if renamed: + # Records each rename against the message id it already has, so the + # tags survive and no new.tags apply. --no-hooks, or this hook would + # run itself. + # + # ponytail: this also indexes any file that landed after the outer + # `notmuch new`, and the closing `-new` then consumes its marker + # unseen by the rules. Under mailsync.sh mbsync has finished and the + # lock is held, so nothing lands. If the hook ever runs beside a live + # mbsync, scope the closing `-new` to the ids seen before this call. + result = subprocess.run(["notmuch", "new", "--no-hooks", "--quiet"], + capture_output=True, text=True) + if result.returncode != 0: + log(f"notmuch new after moving failed: {result.stderr.strip()}") + return False + + for message_id, role, origin in to_tag: + # What Mark spam and Delete add, minus `unread`: the hook still never + # removes that unattended (PROTECTED_REMOVALS). + arguments = ["+spam" if role == "spam" else "+deleted", "-inbox"] + if origin: + arguments.append(f"+moved-from:{origin}") + if not run_tag(arguments, f"id:{_quote(message_id)}"): + return False + + log(f"moved {sum(1 for _, _, o in to_tag if o)} message(s), " + f"tagged {len(to_tag)}") + return True +``` + +In `main()`, the rules loop: collect the rules that ran, and skip the +`notmuch tag` call for a move-only rule (no tag operations to pass): + +```python + applied = [] + for rule in mailrules.ordered(store.rules): + refused = protected_removals(rule) + if refused: + log(f"rule '{rule.id}' would remove {', '.join(refused)}; " + f"skipped, this hook does not remove those unattended") + continue + + arguments = mailrules.tag_arguments(rule) + query = mailrules.scoped_query(rule, SCOPE) + if arguments and not run_tag(arguments, query): + log(f"rule '{rule.id}' failed; leaving tag:new in place") + return 1 + applied.append(rule) + + # After every tag stage, so a later rule still sees mail in its arrival + # folder; before the marker goes, because the marker scopes the moves. + if not apply_moves(applied): + log("moving failed; leaving tag:new in place") + return 1 +``` + +Keep the existing comment block inside the loop. Change the closing log line +to `log(f"applied {len(applied)} rule(s)")`. + +- [ ] **Step 6: Run, expect all pass** + +Run: `cd assets/hooks && ./test_post_new.py && ./test_mailrules.py && ./test_qtmaildirconf.py` + +If `test_the_hook_can_move_when_notmuch_new_itself_runs_it` fails on the +`notmuch new` return code with a lock error, STOP and report to the user. The +fallback is a design change. + +--- + +### Task 4: `TagRule::move` in C++ + +**Files:** +- Modify: `src/tagrules.h:32-48`, `src/tagrules.cpp` (`isKnownKey`, `validate`, `load`, `save`) +- Test: `tests/test_tagrules.cpp` + +- [ ] **Step 1: Write the failing tests.** Declare in the class's private slots after `unknownFieldsSurviveASave();`: + +```cpp + void aMoveRoleRoundTripsAndAMoveOnlyRuleIsValid(); + void anUnknownMoveRoleIsRefused(); +``` + +Define after `TestTagRules::unknownFieldsSurviveASave()`: + +```cpp +void TestTagRules::aMoveRoleRoundTripsAndAMoveOnlyRuleIsValid() +{ + const QString path = writeRules(R"({ + "version": 1, + "rules": [ + {"id": "junk", "query": "from:spammer@example.net", "move": "spam"}, + {"id": "plain", "query": "from:a@example.com", "add": ["x"]} + ] + })"); + + TagRules rules; + rules.load(path); + QVERIFY2(rules.warnings().isEmpty(), + qPrintable(rules.warnings().join(QStringLiteral("; ")))); + QCOMPARE(rules.rules().size(), 2); + QCOMPARE(rules.rules().at(0).move, QStringLiteral("spam")); + QVERIFY(!rules.rules().at(0).unknown.contains(QStringLiteral("move"))); + QVERIFY(TagRules::validate(rules.rules()).isEmpty()); + + QVERIFY(rules.save(path)); + QFile file(path); + QVERIFY(file.open(QIODevice::ReadOnly)); + const QJsonArray saved = QJsonDocument::fromJson(file.readAll()) + .object().value(QStringLiteral("rules")) + .toArray(); + QCOMPARE(saved.at(0).toObject().value(QStringLiteral("move")).toString(), + QStringLiteral("spam")); + // Absent stays absent: an empty `move` on every rule would rewrite every + // file the dialog opens, a diff the hook's reader never asked for. + QVERIFY(!saved.at(1).toObject().contains(QStringLiteral("move"))); +} + +void TestTagRules::anUnknownMoveRoleIsRefused() +{ + TagRule rule; + rule.id = QStringLiteral("odd"); + rule.query = QStringLiteral("from:a@example.com"); + rule.move = QStringLiteral("Archive"); + QCOMPARE(TagRules::validate({ rule }).size(), 1); + + // Loaded, the move is dropped with a warning and the tags survive, as + // mailrules.py does: neither reader guesses a destination. + const QString path = writeRules(R"({ + "version": 1, + "rules": [{"id": "odd", "query": "from:a@example.com", + "add": ["x"], "move": "Archive"}] + })"); + TagRules rules; + rules.load(path); + QCOMPARE(rules.rules().size(), 1); + QVERIFY(rules.rules().at(0).move.isEmpty()); + QCOMPARE(rules.warnings().size(), 1); +} +``` + +- [ ] **Step 2: Build, expect a COMPILE failure** (`TagRule` has no `move`) + +Run: `cmake --build build` + +- [ ] **Step 3: Implement** + +`src/tagrules.h`, in `TagRule` after `remove`: + +```cpp + /// "spam" or "trash", or empty. An account ROLE, never a folder name: the + /// hook resolves it per message to that account's configured folder, so + /// a typo cannot create a folder on the server (item 103, item 214). + QString move; +``` + +`src/tagrules.cpp`, `isKnownKey`: add `QStringLiteral("move"),` to the list. +In the anonymous namespace, after `stringsOf`: + +```cpp +/// What `move` may say. mailrules.py and qtmaildirconf.py carry the same two. +bool isMoveRole(const QString &role) +{ + return role == QStringLiteral("spam") || role == QStringLiteral("trash"); +} +``` + +`validate()`, replacing the add/remove check: + +```cpp + if (!rule.move.isEmpty() && !isMoveRole(rule.move)) { + problems.append(QObject::tr("'%1': move '%2' is not spam or trash") + .arg(where, rule.move)); + } + if (rule.add.isEmpty() && rule.remove.isEmpty() && rule.move.isEmpty()) + problems.append(QObject::tr("'%1': adds, removes and moves nothing") + .arg(where)); +``` + +`load()`, replacing the add/remove block: + +```cpp + rule.add = stringsOf(object.value(QStringLiteral("add"))); + rule.remove = stringsOf(object.value(QStringLiteral("remove"))); + rule.move = object.value(QStringLiteral("move")).toString(); + if (!rule.move.isEmpty() && !isMoveRole(rule.move)) { + m_warnings.append(QObject::tr("Rule '%1': move '%2' is not spam " + "or trash; ignored") + .arg(rule.id, rule.move)); + rule.move.clear(); + } + if (rule.add.isEmpty() && rule.remove.isEmpty() && rule.move.isEmpty()) { + m_warnings.append(QObject::tr("Rule '%1': adds, removes and moves " + "nothing; dropped").arg(rule.id)); + continue; + } +``` + +`save()`, after inserting `remove`: + +```cpp + // Only when set: a file with no moves stays byte-identical on save. + if (!rule.move.isEmpty()) + object.insert(QStringLiteral("move"), rule.move); +``` + +- [ ] **Step 4: Build and run, expect all pass** + +Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_tagrules` + +--- + +### Task 5: the dialog's *Move to* combo + +**Files:** +- Modify: `src/tagrulesdialog.h` (member, two test hooks), `src/tagrulesdialog.cpp` (form at :161-175, connects at :349-360, load at :646, apply at :702) +- Test: `tests/test_tagrules.cpp` + +- [ ] **Step 1: Write the failing test.** Declare `void theDialogWritesTheChosenMoveRole();` and define after `aRuleAddedAndNamedInTheDialogSurvivesAReopen()`: + +```cpp +void TestTagRules::theDialogWritesTheChosenMoveRole() +{ + QTemporaryDir configHome; + QVERIFY(configHome.isValid()); + qputenv("XDG_CONFIG_HOME", configHome.path().toUtf8()); + QVERIFY(QDir().mkpath(configHome.filePath(QStringLiteral("mailrules")))); + + const QString stored = configHome.filePath( + QStringLiteral("mailrules/rules.json")); + QFile out(stored); + QVERIFY(out.open(QIODevice::WriteOnly)); + out.write(R"({ + "version": 1, + "rules": [ + {"id": "vendor", "query": "from:vendor.example.org", + "add": ["vendor"], "stage": 50, "enabled": true} + ] + })"); + out.close(); + + { + TagRulesDialog dialog; + dialog.selectRuleForTest(0); + QCOMPARE(dialog.moveForTest(), QString()); + dialog.setMoveForTest(QStringLiteral("spam")); + dialog.saveForTest(); + QVERIFY(dialog.warningTextForTest().isEmpty()); + } + + TagRules reloaded; + reloaded.load(stored); + QCOMPARE(reloaded.rules().at(0).move, QStringLiteral("spam")); + + // And back the other way: the stored role shows on reopen, so the next + // save cannot silently clear it. + TagRulesDialog reopened; + reopened.selectRuleForTest(0); + QCOMPARE(reopened.moveForTest(), QStringLiteral("spam")); +} +``` + +- [ ] **Step 2: Build, expect a COMPILE failure** (no `moveForTest`) + +- [ ] **Step 3: Implement** + +`src/tagrulesdialog.h`, beside `void setTagsForTest(const QString &tags);`: + +```cpp + void setMoveForTest(const QString &role); + QString moveForTest() const; +``` + +and the member after `QLineEdit *m_remove = nullptr;`: + +```cpp + QComboBox *m_move = nullptr; +``` + +`src/tagrulesdialog.cpp`, after `m_remove` is created: + +```cpp + // The stored value is the item DATA, the wire-format role. The label is + // translated, and nothing may match on it ("Translating a string that + // something MATCHES on" in AGENTS.md). + m_move = new QComboBox(this); + m_move->addItem(tr("Don't move"), QString()); + m_move->addItem(tr("Spam folder"), QStringLiteral("spam")); + m_move->addItem(tr("Trash folder"), QStringLiteral("trash")); + m_move->setToolTip(tr("Moves matching new mail into the spam or trash " + "folder of the account it arrived in, and takes it " + "out of the inbox. It stays unread.")); +``` + +after `form->addRow(tr("Remove tags"), m_remove);`: + +```cpp + form->addRow(tr("Move to"), m_move); +``` + +with the other connects: + +```cpp + connect(m_move, &QComboBox::currentIndexChanged, + this, &TagRulesDialog::applyEditsToCurrentRule); +``` + +in the rule load, after `m_remove->setText(...)`: + +```cpp + m_move->setCurrentIndex(qMax(0, m_move->findData(rule.move))); +``` + +in `applyEditsToCurrentRule`, after `rule.remove = ...`: + +```cpp + rule.move = m_move->currentData().toString(); +``` + +and the hooks, beside `setTagsForTest`: + +```cpp +void TagRulesDialog::setMoveForTest(const QString &role) +{ + m_move->setCurrentIndex(m_move->findData(role)); +} + +QString TagRulesDialog::moveForTest() const +{ + return m_move->currentData().toString(); +} +``` + +- [ ] **Step 4: Build and run, expect all pass** + +Run: `cmake --build build && QT_QPA_PLATFORM=offscreen ./build/tests/test_tagrules` + +--- + +### Task 6: translations, changelog, backlog, 212's note + +**Files:** +- Modify: `translations/qtmaildir_it_IT.ts`, `CHANGELOG.md`, `docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md`, `docs/superpowers/specs/2026-10-31-rule-apply-and-archive-design.md` + +- [ ] **Step 1: Refresh the catalogue** + +Run: `lupdate-qt6 src/ -ts translations/qtmaildir_it_IT.ts -no-obsolete -locations none` +Expected: zero context warnings, new entries marked `type="unfinished"`. + +- [ ] **Step 2: Translate each new entry** (remove `type="unfinished"`): + +| source | translation | +|---|---| +| `Don't move` | `Non spostare` | +| `Spam folder` | `Cartella spam` | +| `Trash folder` | `Cestino` | +| `Move to` | `Sposta in` | +| the tooltip | `Sposta la posta nuova corrispondente nella cartella spam o nel cestino dell'account in cui è arrivata, e la toglie dalla posta in arrivo. Resta da leggere.` | +| `'%1': move '%2' is not spam or trash` | `'%1': lo spostamento '%2' non è spam né cestino` | +| `Rule '%1': move '%2' is not spam or trash; ignored` | `Regola '%1': lo spostamento '%2' non è spam né cestino; ignorato` | +| `'%1': adds, removes and moves nothing` | `'%1': non aggiunge, non rimuove e non sposta nulla` | +| `Rule '%1': adds, removes and moves nothing; dropped` | `Regola '%1': non aggiunge, non rimuove e non sposta nulla; scartata` | + +In the `.ts` file apostrophes are `'`; match the file's existing escaping. + +- [ ] **Step 3: Full suite** + +Run: `cmake --build build && ctest --test-dir build --output-on-failure` +Expected: all pass, including `translations` and the three `hooks_*` tests. + +- [ ] **Step 4: Changelog.** Under `## [Unreleased]` → `### Added`: + +```markdown +- A tagging rule can move the mail it matches into the spam or trash + folder, through a new **Move to** field in the rules dialog. Each message + goes to the folder its own account configures (`spam` / `trash`), never to + a folder named in the rule, and leaves the inbox while staying unread. It + applies to mail as it arrives; Restore and Not spam work on it as on a + message moved by hand. +``` + +- [ ] **Step 5: Item 212's spec.** Append to the end of `docs/superpowers/specs/2026-10-31-rule-apply-and-archive-design.md`: + +```markdown +## Addendum, 2026-11-16: rules that move (item 214) + +A rule may now carry `"move": "spam" | "trash"`. When Apply is built it must +honour that field by sending the matched ids through +`NotmuchWorker::moveMessages()` with the same tags Mark spam / Delete use +(minus `unread`, matching the hook), so the move lands on the undo stack. +The count in the confirmation names the move as well as the tag change. +``` + +- [ ] **Step 6: Backlog row 214** in `docs/superpowers/plans/2026-08-03-post-0.1.0-usability.md`: status cell becomes `built 2026-MM-DD on \`rule-move\`, awaiting the user's hand test`, keeping the rest of the cell. + +--- + +### Task 7: hand-over (stop here) + +- [ ] **Step 1:** Report to the user, without committing: + - suite result (counts from `ctest`) + - the hand round trip they need to run, from AGENTS.md "Changing the rule format": in the worktree build, open the rules dialog (`./build/src/qtmaildir` is theirs to launch), set a rule's *Move to* to Spam folder, save; confirm `~/.config/mailrules/rules.json` carries `"move": "spam"` on that rule and that every other rule is byte-identical (`git diff --no-index` against a copy taken first); then run `assets/hooks/test_post_new.py` once more. + - that the LIVE hook is untouched until the merge, because the live `hook_dir` points at the main checkout. +- [ ] **Step 2:** On the user's go-ahead: commit in the worktree (GPG-signed, one commit per concern: hook + Python readers; C++ reader + dialog; translations + docs), merge `rule-move` into `master`, delete the local branch only, remove the worktree, push. |
