From c747c95c49e681160da8de7f4fe3eed6adc47bba Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Sat, 12 Sep 2026 09:59:56 +0200 Subject: docs: implementation plan for mail-overview Seven tasks, ordered so the thing most likely to be wrong is checked first. The watcher script comes before any QML because it is the only piece with a real runnable check and needs no compositor. The component skeleton gets its own commit because the failure it guards against is invisible: a config whose only window is hidden exits straight after logging Configuration Loaded and reports no error. Two decisions changed while reading the existing components. The drawer is a fullscreen overlay with content anchored top right, which is the idiom both other panels use and what gives click-outside and Escape for free, rather than a small anchored window. And its exclusionMode is Normal rather than the Ignore those two use, so waybar's exclusive zone places it below the bar without this component carrying the bar's 42px height as a constant to drift. Also records a trap measured this session: notmuch exits 0 even for a malformed query, printing something that is not a count, so every count is validated as an integer rather than trusting the exit status. A failure that rendered as 0 would look exactly like an empty inbox. The live-config task needs real absolute paths, because waybar's exec and Hyprland's Lua strings do not expand a tilde. They are written as and placeholders with a note to substitute, since the gitleaks hook blocks committed home paths and was right to reject the first attempt. The spec was updated to match both changes. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01WWL8JYHu7yhAdtx5pU9PMU --- docs/superpowers/plans/2026-09-12-mail-overview.md | 1339 ++++++++++++++++++++ 1 file changed, 1339 insertions(+) create mode 100644 docs/superpowers/plans/2026-09-12-mail-overview.md (limited to 'docs/superpowers/plans') diff --git a/docs/superpowers/plans/2026-09-12-mail-overview.md b/docs/superpowers/plans/2026-09-12-mail-overview.md new file mode 100644 index 0000000..63da50b --- /dev/null +++ b/docs/superpowers/plans/2026-09-12-mail-overview.md @@ -0,0 +1,1339 @@ +# mail-overview 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 fourth quickshell component: one waybar icon carrying the total +unread count across all notmuch accounts, which opens a drawer showing per +account counts and the three newest unread threads per account. + +**Architecture:** Two independent readers of the notmuch database, no shared +state and no daemon. A waybar `custom` module in continuous mode watches the +xapian directory with `inotifywait` and prints one JSON line per commit. A +quickshell component parses `qtmaildir.conf` for the account list and runs +`notmuch` when its drawer opens. The drawer is a fullscreen layershell overlay +with content anchored top right, matching `vm-manager` and `appearance`. + +**Tech Stack:** quickshell 0.3.1 (QML, `Quickshell.Io` `Process`/`FileView`, +`Quickshell.Wayland` layershell), notmuch 0.39 CLI, inotify-tools 4.23, +bash, waybar. + +**Spec:** `docs/superpowers/specs/2026-09-12-mail-overview-design.md` + +--- + +## Before starting + +Read `AGENTS.md` at the repo root. Four traps in it cost real time and this +plan depends on all four: + +1. A quickshell config with no visible window exits silently. Task 2 adds the + 1x1 keepalive window and it is not optional. +2. A detached `qs` does not survive an agent's tool call. Start it so the + harness owns the process and verify from its log, never from a later + `pgrep`. +3. The process is `qs`, not `quickshell`. Use `pkill -x qs` and `pgrep -cx qs`. + Never `-f`, which matches the caller's own command line. +4. QML's JS engine has no `String.matchAll`. Use an `exec` loop. + +Read `appearance/Udt.qml` before Task 3. It is the closest existing analogue to +`Accounts.qml`: a singleton that watches a config file, parses it with an exec +loop, and drives a sequence of commands through one reused `Process`. + +## Facts established by measurement + +Do not re-derive these; they are why the code looks the way it does. + +- Waybar runs on `DP-1` only, anchored top, 42px tall, `layer: top`, with no + `position` key (top is the default) and `margin: 0`. +- There are **five** accounts, with notmuch tags `account-` where `` + matches an `[account.]` section in `qtmaildir.conf`. +- `notmuch` exits **0 even for a malformed query**: `notmuch count 'tag:unread + and (('` printed `40` and exited 0. Exit status alone cannot detect failure, + so every count is validated as a non-negative integer before use. +- An empty result is `0` from `count` and `[]` from `search --format=json`, + both with exit 0. That is a legitimate zero, not an error. +- `qtmaildir` accepts no command line arguments, so nothing can ask it to open + a particular thread or account. +- The xapian directory holds `iamglass`, `flintlock`, and three large `.glass` + files. A commit rewrites `iamglass` and replaces files, which is why the + watch is on the directory and not on a filename. + +## File structure + +| File | Responsibility | +| --- | --- | +| `mail-overview/waybar-mail.sh` | Continuous mode watcher. Prints JSON for waybar. Standalone, no QML involvement. | +| `mail-overview/Theme.qml` | Palette. Byte for byte copy of `appearance/Theme.qml`. | +| `mail-overview/Accounts.qml` | Singleton. Parses `qtmaildir.conf`, runs notmuch, exposes the model and a `refresh()`. All data logic. | +| `mail-overview/MailPanel.qml` | The window, the keepalive window, the layout. All presentation. | +| `mail-overview/shell.qml` | `ShellRoot`, instantiates the panel, `IpcHandler` named `mail`. | +| `mail-overview/README.md` | Component notes. | + +Every new `.qml` and `.sh` file starts with the GPLv2 header used by every +other file in the repo, copied from `appearance/shell.qml` lines 1-10. + +--- + +### Task 1: The waybar watcher script + +This is the only piece with a real runnable check, and it works with no QML at +all, so it goes first. + +**Files:** +- Create: `mail-overview/waybar-mail.sh` + +- [ ] **Step 1: Write the check, and watch it fail** + +The script does not exist yet. Run this to see the shape of the failure you are +fixing: + +```bash +cd # the repository working directory +./mail-overview/waybar-mail.sh +``` + +Expected: `bash: ./mail-overview/waybar-mail.sh: No such file or directory` + +- [ ] **Step 2: Write the script** + +Create `mail-overview/waybar-mail.sh` with the GPLv2 header then: + +```bash +#!/bin/bash +# +# Waybar custom module in continuous mode: prints one JSON line per notmuch +# commit, forever, and waybar redraws on each line. Waybar owns this process, +# which is why there is no daemon to supervise and no interval to tune. +# +# The count is the total across every account. A per account breakdown is the +# drawer's job; see mail-overview/README.md. + +set -u + +QUERY='tag:unread and tag:inbox' + +# notmuch knows where its own database is, so this follows a moved database +# without an edit here. +db="$(notmuch config get database.path 2>/dev/null)/xapian" + +emit() { + local n + n="$(notmuch count "$QUERY" 2>/dev/null)" + + # notmuch exits 0 even for a malformed query, printing something that is + # not a count, so the exit status is not the test: the output is. Anything + # that is not a plain number is a failure, and a failure must not render + # as "no new mail". + if [[ ! "$n" =~ ^[0-9]+$ ]]; then + printf '{"text":"!","tooltip":"notmuch count failed","class":"error"}\n' + return + fi + + if [[ "$n" -eq 0 ]]; then + printf '{"text":"","class":"empty"}\n' + else + printf '{"text":"%s","class":"unread"}\n' "$n" + fi +} + +if [[ ! -d "$db" ]]; then + printf '{"text":"!","tooltip":"no notmuch database","class":"error"}\n' + exit 1 +fi + +emit + +while inotifywait -qq -e close_write,moved_to "$db" 2>/dev/null; do + # One commit touches several files. Without this the module redraws three + # or four times per sync with intermediate counts. + sleep 0.3 + emit +done + +# Falling out of the loop means inotifywait itself failed. Say so rather than +# exiting silently, which looks like an empty inbox. +printf '{"text":"!","tooltip":"mail watcher stopped","class":"error"}\n' +exit 1 +``` + +Then make it executable: + +```bash +chmod +x mail-overview/waybar-mail.sh +``` + +- [ ] **Step 3: Verify the first line is correct** + +```bash +./mail-overview/waybar-mail.sh | head -1 +``` + +Expected: a single JSON line whose `text` equals the output of +`notmuch count 'tag:unread and tag:inbox'`, with `"class":"unread"`. Confirm +the two numbers match: + +```bash +notmuch count 'tag:unread and tag:inbox' +``` + +The script will hang after printing, because it is now waiting on inotify. +Ctrl-C it. + +- [ ] **Step 4: Verify it reacts to a database change** + +This is the check that fails if the event set, the directory watch or the +debounce is wrong. In one terminal: + +```bash +./mail-overview/waybar-mail.sh +``` + +In a second terminal, pick any unread message and toggle a tag on it, which +commits to the database without touching the Maildir: + +```bash +id=$(notmuch search --output=messages --limit=1 'tag:unread and tag:inbox') +notmuch tag -unread -- "$id" # count should drop by one +notmuch tag +unread -- "$id" # and come back +``` + +Expected: the first terminal prints a new line within about a second of each +command, with the count one lower, then the original count again. Exactly one +line per command, not three or four: that is the debounce working. + +Ctrl-C the script. + +- [ ] **Step 5: Verify the failure path renders as an error, not as zero** + +Point the script at a query that notmuch accepts and then mangles, by +temporarily editing `QUERY` to `tag:unread and ((` and running it: + +```bash +sed -i "s/^QUERY=.*/QUERY='tag:unread and (('/" mail-overview/waybar-mail.sh +./mail-overview/waybar-mail.sh | head -1 +``` + +Expected: `{"text":"!","tooltip":"notmuch count failed","class":"error"}` + +If it instead prints a number, the integer validation is wrong and a broken +query would silently read as a real count. Restore the query: + +```bash +sed -i "s/^QUERY=.*/QUERY='tag:unread and tag:inbox'/" mail-overview/waybar-mail.sh +./mail-overview/waybar-mail.sh | head -1 +``` + +Expected: the real count again. + +- [ ] **Step 6: Commit** + +```bash +git add mail-overview/waybar-mail.sh +git commit -m "feat(mail-overview): waybar watcher in continuous mode + +Prints one JSON line per notmuch commit rather than polling on an interval, +so the count drops the moment mail is read in qtmaildir and rises the moment +mbsync commits, and waybar owns the watcher process: nothing to supervise on +a machine with no systemd. + +The watch is on the xapian directory, not on a file inside it, because a +commit replaces files and a watch held on a filename dies with it. The short +sleep coalesces the several writes of one commit into one redraw. + +notmuch exits 0 even for a malformed query, printing something that is not a +count, so the output is validated as an integer rather than trusting the exit +status. A failure there renders as an error glyph: a count that silently +reads zero would look exactly like an empty inbox." +``` + +--- + +### Task 2: The component skeleton that stays running + +Before any layout, prove the config loads and keeps running. Getting this +wrong is the trap in `AGENTS.md`: no visible window means a silent exit, and +the symptom is a keybind that does nothing. + +**Files:** +- Create: `mail-overview/Theme.qml` +- Create: `mail-overview/MailPanel.qml` +- Create: `mail-overview/shell.qml` + +- [ ] **Step 1: Copy the theme verbatim** + +```bash +cp appearance/Theme.qml mail-overview/Theme.qml +``` + +Do not edit it and do not add colours to it. It is a fallback for before +`~/.cache/wal/udt-palette.qml` is read; the real palette is generated. A fourth +copy is a known loose end, deliberately out of scope for this plan. + +- [ ] **Step 2: Write the minimal panel with the keepalive window** + +Create `mail-overview/MailPanel.qml` with the GPLv2 header then: + +```qml +import Quickshell +import Quickshell.Wayland +import QtQuick + +Scope { + id: root + + // Waybar runs on this screen, so the drawer belongs here too. + property string monitor: "DP-1" + property bool open: false + + readonly property var screenObj: + Quickshell.screens.find(s => s.name === root.monitor) ?? Quickshell.screens[0] + + function show() { root.open = true; } + function close() { root.open = false; } + function toggle() { root.open ? close() : show(); } + + // Quickshell exits once no window is visible, and this drawer is closed + // most of the time. See AGENTS.md. + PanelWindow { + visible: true + implicitWidth: 1 + implicitHeight: 1 + color: "transparent" + exclusionMode: ExclusionMode.Ignore + mask: Region {} + WlrLayershell.keyboardFocus: WlrKeyboardFocus.None + } +} +``` + +- [ ] **Step 3: Write the shell root** + +Create `mail-overview/shell.qml` with the GPLv2 header then: + +```qml +import Quickshell +import Quickshell.Io + +ShellRoot { + MailPanel { id: panel } + + IpcHandler { + target: "mail" + function toggle() { panel.toggle(); } + function show() { panel.show(); } + function close() { panel.close(); } + } +} +``` + +- [ ] **Step 4: Verify it loads and stays running** + +Start it in the foreground so the harness owns the process. A detached `qs` +does not survive a tool call and a later `pgrep` will report it dead whether +or not the config is sound, which is the second trap in `AGENTS.md`. + +```bash +timeout 10 qs -p mail-overview 2>&1 | tee /tmp/mail-qs.log +``` + +Expected: `Configuration Loaded` in the output, no QML errors, and the command +runs for the full 10 seconds before `timeout` ends it. If it returns in under +a second, the config exited on its own: the keepalive window is wrong. + +- [ ] **Step 5: Verify IPC reaches it** + +In one terminal: + +```bash +qs -p mail-overview +``` + +In a second: + +```bash +qs -p mail-overview ipc call mail toggle && echo "ipc ok" +``` + +Expected: `ipc ok`. Nothing visible happens yet, which is correct: `open` is a +property with no window bound to it so far. + +Stop it: + +```bash +pkill -x qs; pgrep -cx qs +``` + +Expected: `0`. Note `-x`, not `-f`: `pkill -f` would match this shell's own +command line and kill the caller. + +- [ ] **Step 6: Commit** + +```bash +git add mail-overview/Theme.qml mail-overview/MailPanel.qml mail-overview/shell.qml +git commit -m "feat(mail-overview): component skeleton with the keepalive window + +Nothing is drawn yet. This commit exists on its own because the thing most +likely to be wrong at this stage is invisible: a config whose only window is +hidden exits straight after logging Configuration Loaded, reporting no error, +and the symptom is a keybind that appears to do nothing. + +Theme.qml is a verbatim copy of the one in appearance. It is a fallback for +before the generated palette is read, not a palette to grow; deduplicating +the four copies is a separate change." +``` + +--- + +### Task 3: The account model + +All data logic, no presentation. Modelled on `appearance/Udt.qml`: read it +first. + +**Files:** +- Create: `mail-overview/Accounts.qml` + +- [ ] **Step 1: Confirm what the parser has to handle** + +```bash +grep -n '^\[account\.\|^label\|^color' ~/.config/qtmaildir/qtmaildir.conf +``` + +Expected: five `[account.]` headers, each followed by a `label` and a +`color`. Note that at least one key contains a dot of its own, so the key is +everything between `[account.` and the closing `]`, not everything up to the +first dot. + +- [ ] **Step 2: Write the singleton** + +Create `mail-overview/Accounts.qml` with the GPLv2 header then: + +```qml +pragma Singleton + +import Quickshell +import Quickshell.Io +import QtQuick + +// Which accounts exist, how much unread mail each has, and what the newest of +// it is. +// +// The account list is not here. qtmaildir.conf already carries one +// [account.] section per account, where is exactly the suffix of +// the notmuch tag account-, plus a short label and a colour. Parsing that +// means adding an account to qtmaildir makes it appear here with no edit. +Singleton { + id: root + + readonly property string config: `${Quickshell.env("HOME")}/.config/qtmaildir/qtmaildir.conf` + + // Counting by the account-* tag rather than by a path glob is deliberate. + // notmuch deduplicates by message id, so a message that arrived at two of + // the configured addresses is one message with two paths: a path glob + // counts it under both accounts and the rows then sum to more than the + // total the waybar icon shows. The tag is a property of the message, so + // it is singular and the rows always sum to the header. + readonly property string scope: "tag:unread and tag:inbox" + + // [{ key, label, color, count, threads: [{ authors, date, subject }] }] + // count is -1 until known, and stays -1 on failure: see loadNext below. + property var accounts: [] + + property string error: "" + property bool loading: false + + readonly property int total: + accounts.reduce((sum, a) => sum + Math.max(a.count, 0), 0) + + readonly property bool anyUnknown: accounts.some(a => a.count < 0) + + // The config is watched, so adding an account in qtmaildir updates this + // list without restarting the shell. + FileView { + path: root.config + watchChanges: true + onFileChanged: reload() + onLoadFailed: { + root.accounts = []; + root.error = "cannot read qtmaildir.conf"; + } + onLoaded: { + root.accounts = root.parseAccounts(text()); + root.error = root.accounts.length ? "" : "no accounts in qtmaildir.conf"; + root.refresh(); + } + } + + // Sections in file order, which is the display order. + function parseAccounts(conf) { + const out = []; + // QML's JS engine has no String.matchAll, so this is an exec loop. + // At least one key contains a dot of its own, so the key runs to the + // closing bracket rather than to the first dot. + const re = /^\[account\.([^\]]+)\]([^\[]*)/gm; + let m; + while ((m = re.exec(conf)) !== null) { + const key = m[1]; + const body = m[2]; + const field = name => { + const f = body.match(new RegExp(`^\\s*${name}\\s*=\\s*(.+)$`, "m")); + return f ? f[1].trim() : ""; + }; + out.push({ + key: key, + label: field("label") || key, + color: field("color"), + count: -1, + threads: [], + }); + } + return out; + } + + function refresh() { + if (!accounts.length) return; + loading = true; + proc.next = 0; + proc.loadNext(); + } + + // One process per account, in turn, fetching the count and the newest + // three threads together and splitting on a marker: two calls are needed + // because a search limited to three rows cannot report the total, and + // doing them as one command keeps the pair consistent. + Process { + id: proc + property int next: 0 + property int current: 0 + + function loadNext() { + if (next >= root.accounts.length) { + root.loading = false; + return; + } + current = next; + next++; + const q = `${root.scope} and tag:account-${root.accounts[current].key}`; + command = ["sh", "-c", + `notmuch count ${JSON.stringify(q)}; ` + + `echo '===SPLIT==='; ` + + `notmuch search --format=json --limit=3 --sort=newest-first ${JSON.stringify(q)}`]; + // Assigning true to an already-true `running` does nothing, and + // this Process is reused for every account in turn. + running = false; + running = true; + } + + stdout: StdioCollector { + onStreamFinished: { + root.applyResult(proc.current, text); + proc.loadNext(); + } + } + + onExited: code => { + // A non-zero exit leaves this account's count at whatever it was, + // which for a first load is -1 and renders as a dash. Carrying on + // to the next account matters: one failure must not blank the + // whole panel. + if (code !== 0) proc.loadNext(); + } + } + + function applyResult(index, out) { + const parts = out.split("===SPLIT==="); + if (parts.length < 2) return; + + const next = accounts.slice(); + const acct = Object.assign({}, next[index]); + + // notmuch exits 0 even for a malformed query and prints something that + // is not a count, so the output is the test, not the exit status. A + // count that cannot be trusted stays -1 and renders as a dash: a zero + // here would read as "no new mail", which is the same class of + // mistake as showing a libvirt host-side figure as guest memory. + const n = parts[0].trim(); + acct.count = /^\d+$/.test(n) ? parseInt(n, 10) : -1; + + acct.threads = []; + try { + const rows = JSON.parse(parts[1]); + if (Array.isArray(rows)) { + acct.threads = rows.map(r => ({ + authors: String(r.authors ?? ""), + date: String(r.date_relative ?? ""), + subject: String(r.subject ?? "(no subject)"), + })); + } + } catch (e) { + // Keep the count, drop the thread list: a count with no preview is + // still useful, and an empty search is a legitimate "[]". + } + + next[index] = acct; + accounts = next; + } + + // Launching qtmaildir, and syncing. qtmaildir takes no arguments, so + // there is nothing to tell it about the account or thread clicked. + Process { id: openProc; command: [`${Quickshell.env("HOME")}/bin/qtmaildir`] } + + function openClient() { + openProc.running = false; + openProc.running = true; + } + + property bool syncing: false + + // mailsync.sh is already lock-protected against a concurrent cron run, so + // this does not need its own guard beyond not stacking clicks. + Process { + id: syncProc + command: [`${Quickshell.env("HOME")}/bin/mailsync.sh`] + onExited: { + root.syncing = false; + root.refresh(); + } + } + + function sync() { + if (syncing) return; + syncing = true; + syncProc.running = false; + syncProc.running = true; + } +} +``` + +- [ ] **Step 3: Verify the parse and the counts from the log** + +Add a temporary probe to `mail-overview/shell.qml`, inside `ShellRoot`: + +```qml + Component.onCompleted: Qt.callLater(() => { + console.log("ACCOUNTS", JSON.stringify(Accounts.accounts.map(a => a.key + ":" + a.label))); + }) + Connections { + target: Accounts + function onLoadingChanged() { + if (!Accounts.loading) + console.log("COUNTS", JSON.stringify(Accounts.accounts.map(a => a.label + "=" + a.count)), + "total", Accounts.total); + } + } +``` + +Run it: + +```bash +timeout 25 qs -p mail-overview 2>&1 | grep -E 'ACCOUNTS|COUNTS|error|Error' +``` + +Expected: an `ACCOUNTS` line with five `key:label` pairs in config order, then +a `COUNTS` line where every value is a non-negative number, no `-1`, and +`total` equals: + +```bash +notmuch count 'tag:unread and tag:inbox' +``` + +Those two numbers must match exactly. If `total` is higher, something is +counting by path rather than by tag. + +A `-1` for an account means its `notmuch` call failed; read the surrounding log +lines before continuing. Do not accept a `0` you have not verified against +`notmuch count 'tag:unread and tag:inbox and tag:account-'`. + +- [ ] **Step 4: Remove the probe** + +Delete the `Component.onCompleted` block and the `Connections` block added in +Step 3 from `mail-overview/shell.qml`. They were scaffolding for the check, not +part of the component. + +Verify it still loads clean: + +```bash +timeout 10 qs -p mail-overview 2>&1 | grep -cE 'Error|error:' +``` + +Expected: `0`. + +- [ ] **Step 5: Commit** + +```bash +git add mail-overview/Accounts.qml mail-overview/shell.qml +git commit -m "feat(mail-overview): account model from qtmaildir.conf + +The account list lives in qtmaildir.conf, not here: its [account.] +sections already name every account, and is exactly the suffix of the +notmuch tag account-, with a short label and a colour alongside. Parsing +that file means adding an account to qtmaildir makes it appear in the drawer +with no edit to any QML. The file is watched, so that happens without a +restart. + +Counting uses the account tag rather than a path glob. notmuch deduplicates +by message id, so a message that arrived at two configured addresses is one +message with two paths: a glob counts it under both accounts and the rows +then sum higher than the total the waybar icon shows, measured here as 102 +against 101. + +notmuch exits 0 even for a malformed query, so the output is validated as an +integer rather than trusting the exit status, and a count that cannot be +trusted stays -1 to render as a dash. A zero there would read as an empty +inbox, which is the same class of mistake as reporting a libvirt host-side +figure as guest memory." +``` + +--- + +### Task 4: The drawer + +All presentation. The window idiom is a fullscreen overlay with the content +anchored where the drawer belongs, which is what both `vm-manager` and +`appearance` do. + +**Files:** +- Modify: `mail-overview/MailPanel.qml` (the file from Task 2; add the drawer + below the keepalive window) + +- [ ] **Step 1: Refresh on open** + +In `mail-overview/MailPanel.qml`, replace the `show()` function written in +Task 2 with: + +```qml + function show() { + // Mail has almost certainly arrived since this was last opened, and + // for an autostarted shell that is the whole session. + Accounts.refresh(); + root.open = true; + } +``` + +- [ ] **Step 2: Add the drawer window** + +Append inside the `Scope`, after the keepalive `PanelWindow`: + +```qml + LazyLoader { + active: root.open + + PanelWindow { + id: win + screen: root.screenObj + + anchors { top: true; left: true; right: true; bottom: true } + color: "transparent" + + // Normal, not Ignore: waybar claims an exclusive zone at the top + // of this screen, so respecting it puts the drawer below the bar + // without this file knowing the bar's height. The backdrop then + // starts below waybar too, which is why waybar stays un-dimmed. + exclusionMode: ExclusionMode.Normal + + WlrLayershell.layer: WlrLayer.Overlay + WlrLayershell.namespace: "quickshell-mail" + WlrLayershell.keyboardFocus: WlrKeyboardFocus.Exclusive + + Rectangle { + anchors.fill: parent + color: "#000000" + opacity: 0.5 + MouseArea { anchors.fill: parent; onClicked: root.close() } + } + + // Keys reach a focused item, never the window itself: setting + // keyboardFocus above is necessary but not sufficient, and + // Keys.onEscapePressed on a PanelWindow never fires. + Item { + anchors.fill: parent + focus: true + Keys.onEscapePressed: root.close() + } + + // Top right, under the waybar icon, which sits in modules-right. + Rectangle { + id: drawer + anchors { top: parent.top; right: parent.right; topMargin: 8; rightMargin: 8 } + width: 460 + height: Math.min(content.implicitHeight + 32, win.height - 24) + radius: 14 + color: Qt.alpha(Theme.base, 0.72) + border.width: 1 + border.color: Qt.alpha(Theme.text, 0.12) + + // Swallows clicks so they do not reach the backdrop and close + // the drawer. + MouseArea { anchors.fill: parent } + + Column { + id: content + anchors { left: parent.left; right: parent.right; top: parent.top; margins: 16 } + spacing: 10 + + // Header + Item { + width: parent.width + implicitHeight: Math.max(title.implicitHeight, totalText.implicitHeight) + + Text { + id: title + anchors.verticalCenter: parent.verticalCenter + text: "Mail" + color: Theme.text + font.family: Theme.fontFamily + font.pixelSize: Theme.fontSize + 2 + font.bold: true + } + + Text { + id: totalText + anchors { right: parent.right; verticalCenter: parent.verticalCenter } + // A dash rather than a possibly-wrong number while + // any account is still unknown. + text: Accounts.anyUnknown ? "—" : `${Accounts.total} unread` + color: Theme.subtext + font.family: Theme.fontFamily + font.pixelSize: Theme.fontSize + } + } + + Rectangle { width: parent.width; height: 1; color: Qt.alpha(Theme.text, 0.12) } + + Text { + visible: Accounts.error !== "" + width: parent.width + text: Accounts.error + color: Theme.red + wrapMode: Text.WordWrap + font.family: Theme.fontFamily + font.pixelSize: Theme.fontSize - 2 + } + + Repeater { + model: Accounts.accounts + + Column { + required property var modelData + width: content.width + spacing: 4 + + Item { + width: parent.width + implicitHeight: 26 + + Rectangle { + id: dot + anchors.verticalCenter: parent.verticalCenter + width: 8; height: 8; radius: 4 + // The account's own colour from the config. + // Per-account identity, not a palette. + color: modelData.color || Theme.accent + } + + Text { + anchors { left: dot.right; leftMargin: 10; verticalCenter: parent.verticalCenter } + text: modelData.label + color: Theme.text + font.family: Theme.fontFamily + font.pixelSize: Theme.fontSize + } + + Text { + anchors { right: parent.right; verticalCenter: parent.verticalCenter } + text: modelData.count < 0 ? "—" : String(modelData.count) + color: modelData.count > 0 ? Theme.text : Theme.subtext + font.family: Theme.fontFamily + font.pixelSize: Theme.fontSize + font.bold: modelData.count > 0 + } + } + + // The newest three unread threads. Read-only: + // qtmaildir takes no arguments, so there is no way + // to ask it for a particular thread. + Repeater { + model: modelData.threads + + Column { + required property var modelData + width: content.width - 18 + x: 18 + spacing: 1 + bottomPadding: 4 + + Item { + width: parent.width + implicitHeight: who.implicitHeight + + Text { + id: who + anchors.left: parent.left + width: parent.width - when.implicitWidth - 10 + text: modelData.authors + elide: Text.ElideRight + color: Theme.subtext + font.family: Theme.fontFamily + font.pixelSize: Theme.fontSize - 3 + } + + Text { + id: when + anchors.right: parent.right + text: modelData.date + color: Theme.overlay + font.family: Theme.fontFamily + font.pixelSize: Theme.fontSize - 3 + } + } + + Text { + width: parent.width + text: modelData.subject + elide: Text.ElideRight + color: Theme.text + font.family: Theme.fontFamily + font.pixelSize: Theme.fontSize - 2 + } + } + } + } + } + + Rectangle { width: parent.width; height: 1; color: Qt.alpha(Theme.text, 0.12) } + + Row { + anchors.right: parent.right + spacing: 10 + + Button { + text: Accounts.syncing ? "Syncing..." : "Sync now" + enabled: !Accounts.syncing + onClicked: Accounts.sync() + } + + Button { + text: "Open qtmaildir" + onClicked: { Accounts.openClient(); root.close(); } + } + } + } + } + } + } +``` + +- [ ] **Step 3: Add the button component** + +`vm-manager/Button.qml` is a plain styled button with exactly this job. Copy it +rather than writing a second one: + +```bash +cp vm-manager/Button.qml mail-overview/Button.qml +``` + +Then confirm it exposes `text`, `enabled` and `onClicked` as used above: + +```bash +grep -n 'property\|signal\|clicked' mail-overview/Button.qml +``` + +If it does not expose an `enabled` property, add one and make the background +and label dim when false: + +```qml + property bool enabled: true + opacity: enabled ? 1 : 0.45 +``` + +and guard the click: + +```qml + onClicked: if (root.enabled) root.clicked() +``` + +matching whatever identifiers the copied file actually uses. + +- [ ] **Step 4: Verify it opens, shows real numbers, and closes** + +```bash +qs -p mail-overview +``` + +In a second terminal: + +```bash +qs -p mail-overview ipc call mail toggle +``` + +Check, by looking at the screen: + +- the drawer is at the top right, below waybar, not overlapping it +- five accounts in config order, each with a coloured dot and its label +- every count is a number, not a dash +- the accounts with unread mail show up to three author/date/subject lines +- the header total equals the sum of the rows + +Then confirm both closes work: press Escape, reopen with the same IPC call, and +click the dimmed area away from the drawer. + +Verify the counts against notmuch rather than trusting the screen: + +```bash +for k in $(grep -oP '^\[account\.\K[^\]]+' ~/.config/qtmaildir/qtmaildir.conf); do + printf '%-32s %s\n' "$k" "$(notmuch count "tag:unread and tag:inbox and tag:account-$k")" +done +notmuch count 'tag:unread and tag:inbox' +``` + +Stop it: + +```bash +pkill -x qs; pgrep -cx qs +``` + +Expected: `0`. + +The visual result is the user's to judge. Ask them to look; do not screenshot +a transient drawer. + +- [ ] **Step 5: Commit** + +```bash +git add mail-overview/MailPanel.qml mail-overview/Button.qml +git commit -m "feat(mail-overview): the drawer + +A fullscreen layershell overlay with the content anchored top right, which is +the idiom both other panels in this repo use, and which gives click-outside +and Escape for free. + +exclusionMode is Normal rather than Ignore, unlike the other two: waybar +claims an exclusive zone at the top of this screen, so respecting it places +the drawer under the bar without this file carrying the bar's height as a +constant to drift. It also leaves waybar outside the dimmed backdrop. + +Focus is on an inner Item, not the window. Setting keyboardFocus is necessary +but not sufficient: key events reach a focused item, and Keys.onEscapePressed +on a PanelWindow never fires. + +Thread rows are read-only because qtmaildir accepts no arguments, so there is +nothing to tell it which thread was clicked. An unknown count renders as a +dash rather than a zero." +``` + +--- + +### Task 5: The README + +**Files:** +- Create: `mail-overview/README.md` + +- [ ] **Step 1: Write it** + +Follow the shape of `appearance/README.md`. It must cover, in prose: + +- what the component is: one waybar icon with the total, a drawer with per + account counts and the newest three unread threads each +- that the account list comes from `qtmaildir.conf` `[account.]` sections, + that `` is the notmuch tag suffix, and that adding an account there is + all that is needed +- why counting uses the `account-*` tag and not a path glob, with the + deduplication reason and the 102-against-101 measurement +- that every count is `tag:unread and tag:inbox`, and what plain `tag:unread` + would include instead +- that `notmuch` exits 0 for a malformed query, so counts are validated as + integers and an untrusted count shows a dash +- that the waybar module runs in continuous mode, why the watch is on the + xapian directory rather than a file, and what the debounce is for +- that `exclusionMode: ExclusionMode.Normal` is what puts the drawer under + waybar, and that this differs from the other two components +- that thread rows are read-only because `qtmaildir` takes no arguments +- how to run it: `qs -p mail-overview`, and + `qs -p mail-overview ipc call mail toggle` +- the live config needed outside the repo, described with `~` paths only: the + waybar module, the Hyprland layer rule for namespace `quickshell-mail`, and + the autostart line + +No absolute home paths anywhere in the file. A gitleaks hook blocks them. + +- [ ] **Step 2: Check for home paths before committing** + +```bash +grep -n '/home/' mail-overview/README.md mail-overview/*.qml mail-overview/*.sh +``` + +Expected: no output. If anything matches, replace it with a `~` path. + +- [ ] **Step 3: Commit** + +```bash +git add mail-overview/README.md +git commit -m "docs(mail-overview): component notes + +Records the two decisions a later reader would otherwise reverse: counting by +the account tag rather than a path glob, and validating notmuch output as an +integer because it exits 0 even for a malformed query." +``` + +--- + +### Task 6: Repo documentation + +**Files:** +- Modify: `README.md` +- Modify: `AGENTS.md` + +- [ ] **Step 1: Add the component to the repo README** + +Read the existing list of components in `README.md` and add a `mail-overview` +entry in the same style as the other three: one line saying it is a notmuch +mail overview drawer with a waybar icon carrying the total. + +- [ ] **Step 2: Add the component to the AGENTS.md inventory** + +In `AGENTS.md`, the "What this is" section lists the components: + +``` + volume-osd/ volume for output and input, plus what is playing + vm-manager/ libvirt drawer: state, live stats, snapshots + appearance/ wallpaper picker and colour scheme switcher +``` + +Add a fourth line in the same format: + +``` + mail-overview/ notmuch unread counts per account, waybar icon and drawer +``` + +The sentence below that block says "Both are started from" and then "Both +components here are hidden most of the time" in the next section. With four +components those are wrong; change "Both" to "They" and "Both components here +are" to "These components are". + +- [ ] **Step 3: Add the generalising notes** + +Still in `AGENTS.md`, the "Per-component notes" section collects the traps that +generalise. Add three bullets in the existing style: + +```markdown +- **`notmuch` exits 0 even for a malformed query.** It prints something that + is not a count and returns success, so the exit status cannot detect + failure: validate the output as an integer. A failure that renders as `0` + reads as an empty inbox. +- **notmuch deduplicates by message id, so one message can have several + paths.** A message that arrived at two configured addresses is counted by + both accounts under a `path:` glob, and per-account counts then sum above + the total. The `account-*` tag is a property of the message, so it is + singular. +- **Xapian replaces files on commit.** A watch held on a filename inside the + database directory dies with the file; watch the directory for + `close_write,moved_to` instead. +``` + +- [ ] **Step 4: Add the exclusion-zone note to the Blur section** + +The "Blur" section in `AGENTS.md` already says a new component needs its own +`hl.layer_rule` and a distinct namespace. Add, after that: + +```markdown +A panel that should sit below waybar rather than over it wants +`exclusionMode: ExclusionMode.Normal` on its window, which respects waybar's +exclusive zone without the component knowing the bar's height. +`mail-overview` does this; the other two use `ExclusionMode.Ignore` and cover +the whole screen. +``` + +- [ ] **Step 5: Verify no home paths crept in** + +```bash +grep -n '/home/' README.md AGENTS.md +``` + +Expected: no output. + +- [ ] **Step 6: Commit** + +```bash +git add README.md AGENTS.md +git commit -m "docs: add mail-overview to the inventory and its traps to the notes + +Three of them generalise beyond this component: notmuch exits 0 for a +malformed query, notmuch deduplicates by message id so one message can be +counted under two accounts by a path glob, and xapian replaces files on +commit so a watch on a filename dies with it." +``` + +--- + +### Task 7: Live configuration, and retiring the old modules + +These files are the live waybar and Hyprland configuration. They are not in +this repo and are not committed here. Do each one, then verify. + +`` below stands for the absolute path of this repository's working +directory, and `` for the user's home directory. Write the real absolute +paths into these live files: waybar's `exec` and Hyprland's Lua strings do not +expand `~`. They appear as placeholders here only because a gitleaks hook +blocks committed home paths, and it is right to. + +**Files (all outside the repo):** +- Modify: `~/.config/waybar/modules/custom/mail.jsonc` +- Modify: `~/.config/waybar/config.jsonc` +- Modify: `~/.config/hypr/sections/decorations.lua` +- Modify: `~/.config/hypr/sections/autostart.lua` + +- [ ] **Step 1: Back up the two waybar files** + +```bash +cp ~/.config/waybar/modules/custom/mail.jsonc ~/.config/waybar/modules/custom/mail.jsonc.bak-20260912 +cp ~/.config/waybar/config.jsonc ~/.config/waybar/config.jsonc.bak-20260912 +``` + +- [ ] **Step 2: Replace the module definition** + +Replace the entire contents of `~/.config/waybar/modules/custom/mail.jsonc`, +which currently holds three `custom/mail#*` entries polling the Gmail API, +with one module. Use the absolute path to the script, since this file is live +config and not committed: + +```jsonc +{ + "custom/mail": { + "format": "󰃯 {}", + "return-type": "json", + "exec": "/mail-overview/waybar-mail.sh", + "on-click": "qs -p /mail-overview ipc call mail toggle", + "on-click-right": "/bin/mailsync.sh", + "tooltip": false + } +} +``` + +Note there is no `interval`: the script never exits and prints a line per +database commit. + +- [ ] **Step 3: Replace the three module names in the bar** + +In `~/.config/waybar/config.jsonc`, the `modules-right` array contains: + +```jsonc + "custom/mail#danixland", + "custom/mail#itdanilo", + "custom/mail#65danix85", +``` + +Replace those three lines with one: + +```jsonc + "custom/mail", +``` + +- [ ] **Step 4: Reload waybar and verify the icon** + +```bash +pkill -x waybar; sleep 1; (setsid waybar >/dev/null 2>&1 &) ; sleep 3; pgrep -cx waybar +``` + +Expected: `1`. Then confirm on screen that there is one mail icon showing the +total, and that it matches: + +```bash +notmuch count 'tag:unread and tag:inbox' +``` + +Confirm the watcher is attached to waybar rather than leaked: + +```bash +pgrep -af 'waybar-mail.sh' | wc -l +``` + +Expected: `1`. + +- [ ] **Step 5: Add the blur rule** + +In `~/.config/hypr/sections/decorations.lua`, find the existing `hl.layer_rule` +entries for the other components and add one for this namespace, matching their +style: + +```lua +hl.layer_rule("blur", "quickshell-mail") +``` + +Copy the exact form and any companion rules (`ignorealpha`, `ignorezero`) the +others use; without the rule the drawer still works, rendering flat +translucent. + +- [ ] **Step 6: Add the autostart line** + +In `~/.config/hypr/sections/autostart.lua`, find the existing `qs -p` lines and +add one in the same style: + +```lua +"qs -p /mail-overview" +``` + +This matters because the waybar click calls IPC, and IPC needs the shell +already running. + +- [ ] **Step 7: Reload Hyprland and verify end to end** + +```bash +hyprctl reload +sleep 2 +pgrep -cx qs +``` + +Expected: one more `qs` than before the reload, four if all four components +autostart. + +Then confirm the layer exists and is placed below waybar: + +```bash +hyprctl layers | grep -E 'waybar|quickshell-mail' +``` + +Click the waybar mail icon and confirm the drawer opens under the bar. Check +the blur rule took by confirming the drawer is frosted rather than flat. + +- [ ] **Step 8: Confirm the Gmail polling is gone** + +```bash +pgrep -af 'launch.py' | wc -l +``` + +Expected: `0`. Nothing should be polling the Gmail API any more. + +The now-dead files are `~/.config/polybar/modules/gmail/`, holding the python +script and three `credentials_*.json`. Nothing else references them once the +modules are replaced. Ask the user before deleting or archiving: credentials +are theirs to dispose of, and last session's equivalent was archived rather +than removed. + +- [ ] **Step 9: Nothing to commit** + +These files are outside the repo by design. Confirm the repo is clean and that +no live config leaked into it: + +```bash +git status --short # run from the repository root +``` + +Expected: no output. + +--- + +## Final verification + +- [ ] Waybar shows one mail icon whose count equals + `notmuch count 'tag:unread and tag:inbox'` +- [ ] Reading mail in qtmaildir drops that count within about a second, + without a sync +- [ ] Clicking the icon opens the drawer below waybar +- [ ] All five accounts appear, in `qtmaildir.conf` order, with their labels + and colours, and the rows sum to the header +- [ ] Escape and a click outside both close the drawer +- [ ] "Sync now" runs, the button disables while it does, and the counts + update afterwards +- [ ] "Open qtmaildir" launches the client +- [ ] `git status --short` in the repo is empty, and + `grep -rn '/home/' mail-overview/ README.md AGENTS.md` finds nothing +- [ ] The user has looked at the drawer and is happy with how it renders -- cgit v1.2.3