orgwarrior-web 0.1.0__py3-none-any.whl

orgwarrior_web/__init__.py

@@ -0,0 +1,3 @@
+"""The org agenda on a phone: a small web page over orgwarrior's engine."""
+
+__version__ = "0.1.0"

orgwarrior_web/auth.py

@@ -0,0 +1,130 @@
+"""Per-device tokens: each device gets its own random token, named, and the
+server keeps only their hashes, in a state file (not the config, which
+may live in a dotfiles repo).  `orgwarrior-web token add|list|revoke`."""
+
+import argparse
+import datetime
+import hashlib
+import hmac
+import os
+import re
+import secrets
+import sys
+from pathlib import Path
+
+from orgwarrior_web.jsonfile import JsonFile
+
+NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.-]{0,39}")
+
+
+def default_path() -> Path:
+    state = os.environ.get("XDG_STATE_HOME") or Path.home() / ".local/state"
+    return Path(state) / "orgwarrior-web/tokens.json"
+
+
+def digest(token: str) -> str:
+    # A plain hash is enough: the tokens are random, 32 bytes, not passwords.
+    return hashlib.sha256(token.encode()).hexdigest()
+
+
+class Tokens:
+    """The tokens file, {name: {"sha256", "scope", "created"}}, reread when it
+    changes, so `token add`/`revoke` count without restarting the server."""
+
+    def __init__(self, path: Path | None = None):
+        self.file = JsonFile(path or default_path(), dict, 0o600)
+
+    @property
+    def path(self) -> Path:
+        return self.file.path
+
+    def load(self) -> dict:
+        return self.file.load()
+
+    def find(self, token: str) -> tuple[str, str] | None:
+        """(name, scope) of TOKEN, or None.  Scope "full" opens everything,
+        "calendar" only the feed, "add" only adding (someone else's device,
+        adding to this list without seeing it), "mcp" only orgwarrior-mcp
+        (Claude: none of the page)."""
+        d = digest(token)
+        found = None
+        for name, t in self.load().items():
+            if hmac.compare_digest(d, t["sha256"]):
+                found = name, t["scope"]
+        return found
+
+    def add(self, name: str, scope: str = "full") -> str:
+        if not NAME.fullmatch(name):
+            raise ValueError(f"not a token name: {name!r} (letters, digits, _ . -; up to 40)")
+        tokens = dict(self.load())
+        if name in tokens:
+            raise ValueError(f"there is already a token {name!r}: revoke it first")
+        token = secrets.token_urlsafe(32)
+        tokens[name] = {"sha256": digest(token), "scope": scope,
+                        "created": datetime.date.today().isoformat()}
+        self.file.save(tokens)
+        return token
+
+    def revoke(self, name: str):
+        tokens = dict(self.load())
+        if tokens.pop(name, None) is None:
+            raise ValueError(f"no token {name!r}")
+        self.file.save(tokens)
+
+
+def token_main(argv: list[str]) -> int:
+    ap = argparse.ArgumentParser(
+        prog="orgwarrior-web token",
+        description="Manage the tokens that let a device in. Each device gets its own, "
+        "so one can be cut off without the others. Changes count at once, no restart.")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    add = sub.add_parser("add", help="make a token for a device and print its sign-in link")
+    add.add_argument("name", help="what it's for: phone, laptop, ...")
+    scope = add.add_mutually_exclusive_group()
+    scope.add_argument("--calendar", action="store_true",
+                       help="a token for a calendar app: opens the calendar feed and nothing else")
+    scope.add_argument("--add", action="store_true",
+                       help="a token for someone else: adds to your inbox (marked FROM them) "
+                       "and sees nothing")
+    scope.add_argument("--mcp", action="store_true",
+                       help="a token for Claude: opens orgwarrior-mcp and none of the page")
+    add.add_argument("--url", help="the server's address, to print the whole link "
+                     "(e.g. https://10.0.0.5:22546)")
+    sub.add_parser("list", help="the tokens there are")
+    rev = sub.add_parser("revoke", help="cut a device off")
+    rev.add_argument("name")
+    args = ap.parse_args(argv)
+    tokens = Tokens()
+    try:
+        if args.cmd == "add":
+            token = tokens.add(args.name, "calendar" if args.calendar else "add" if args.add
+                               else "mcp" if args.mcp else "full")
+            base = (args.url or "https://HOST:PORT").rstrip("/")
+            if args.mcp:
+                print(f"Connect Claude (or any MCP client) to {base}/mcp\n"
+                      f"with this request header:\n\n"
+                      f"  Authorization: Bearer {token}\n\n"
+                      f"A client that takes only a URL can use this one:\n\n"
+                      f"  {base}/mcp?key={token}\n")
+            elif args.calendar:
+                print(f"Subscribe to this in the calendar app (ICSx\u2075 on Android):\n\n"
+                      f"  {base}/calendar.ics?key={token}\n")
+            else:
+                print(f"Open this once on {args.name}; it then stays signed in:\n\n"
+                      f"  {base}/?key={token}\n\n"
+                      f"On an iPhone, an app added to the home screen doesn't share Safari's\n"
+                      f"sign-in: open it and paste the key there (the part after key=).\n")
+            print(f"It isn't shown again. `orgwarrior-web token revoke {args.name}` cuts it off.")
+        elif args.cmd == "list":
+            listed = tokens.load()
+            if not listed:
+                print("No tokens. `orgwarrior-web token add NAME` makes one.")
+            for name, t in listed.items():
+                print(f"{name:20} {t['scope']:10} made {t['created']}")
+        else:
+            tokens.revoke(args.name)
+            print(f"Revoked {args.name}.")
+    except (ValueError, OSError) as e:
+        print(f"orgwarrior-web token: {e}", file=sys.stderr)
+        return 1
+    return 0

orgwarrior_web/feed.py

@@ -0,0 +1,140 @@
+"""The calendar feed: orgwarrior's dated entries (api.calendar) as
+iCalendar (RFC 5545), read-only, each event linking to its task page."""
+
+import datetime
+import re
+
+from orgwarrior.config import ConfigError
+
+DEFAULTS = {"keywords": True, "deadlines": True, "alarms": True, "alarm_time": "09:00",
+            "deadline_prefix": "Due: "}
+
+FREQ = {"h": "HOURLY", "d": "DAILY", "w": "WEEKLY", "m": "MONTHLY", "y": "YEARLY"}
+# iCalendar durations have no months or years: a warning of 2m is 60 days.
+MINUTES = {"h": 60, "d": 1440, "w": 7 * 1440, "m": 30 * 1440, "y": 365 * 1440}
+
+
+def options(table: dict) -> dict:
+    """[web.calendar] over the defaults, checked at startup like the tabs."""
+    if unknown := set(table) - set(DEFAULTS):
+        raise ConfigError(f"unknown key [web.calendar] {sorted(unknown)[0]!r}")
+    for key in ("keywords", "deadlines", "alarms"):
+        if not isinstance(table.get(key, True), bool):
+            raise ConfigError(f"[web.calendar] {key} is true or false")
+    if not isinstance(table.get("deadline_prefix", ""), str):
+        raise ConfigError('[web.calendar] deadline_prefix is text: "Due: ", or "" for none')
+    if not re.fullmatch(r"([01]\d|2[0-3]):[0-5]\d", str(table.get("alarm_time", "09:00"))):
+        raise ConfigError('[web.calendar] alarm_time is a time of day: "09:00"')
+    return {**DEFAULTS, **table}
+
+
+def escape(text: str) -> str:
+    return (text.replace("\\", "\\\\").replace(";", "\\;").replace(",", "\\,")
+            .replace("\r\n", "\\n").replace("\r", "\\n").replace("\n", "\\n"))
+
+
+def fold(line: str) -> str:
+    """LINE in pieces of at most 75 octets, as the RFC wants, never
+    splitting a UTF-8 character."""
+    out, piece, size = [], "", 0
+    for ch in line:
+        n = len(ch.encode())
+        if size + n > (75 if not out else 74):
+            out.append(piece)
+            piece, size = "", 0
+        piece += ch
+        size += n
+    out.append(piece)
+    return "\r\n ".join(out)
+
+
+def ical_date(iso: str) -> str:
+    return iso.replace("-", "")
+
+
+def ical_time(iso: str, hhmm: str) -> str:
+    return f"{ical_date(iso)}T{hhmm.replace(':', '')}00"
+
+
+def next_day(iso: str) -> str:
+    return (datetime.date.fromisoformat(iso) + datetime.timedelta(days=1)).isoformat()
+
+
+def duration(minutes: int) -> str:
+    sign = "-" if minutes < 0 else ""
+    days, rest = divmod(abs(minutes), 1440)
+    hours, mins = divmod(rest, 60)
+    time = (f"{hours}H" if hours else "") + (f"{mins}M" if mins else "")
+    return f"{sign}P" + (f"{days}D" if days or not time else "") + (f"T{time}" if time else "")
+
+
+def times(stamp: dict) -> list[str]:
+    """DTSTART and DTEND.  Floating times (no time zone): the device's own,
+    as org's are.  All-day ends are exclusive, so a range's last day + 1."""
+    start, end, t0, t1 = stamp["start"], stamp["end"], stamp["start_time"], stamp["end_time"]
+    if not t0:
+        return [f"DTSTART;VALUE=DATE:{ical_date(start)}", f"DTEND;VALUE=DATE:{ical_date(next_day(end))}"]
+    lines = [f"DTSTART:{ical_time(start, t0)}"]
+    if t1 and (end, t1) != (start, t0):
+        lines.append(f"DTEND:{ical_time(end, t1)}")
+    elif end != start:
+        lines.append(f"DTEND:{ical_date(next_day(end))}T000000")
+    return lines
+
+
+def alarm(stamp: dict, opts: dict, summary: str) -> list[str]:
+    """A deadline's warning (-3d) as an alarm that many days ahead: for an
+    all-day deadline, at alarm_time on that day."""
+    warning = stamp.get("warning")
+    if not (opts["alarms"] and stamp["kind"] == "deadline" and warning):
+        return []
+    ahead = warning["value"] * MINUTES[warning["unit"]]
+    if not stamp["start_time"]:
+        h, m = opts["alarm_time"].split(":")
+        ahead -= int(h) * 60 + int(m)
+    return ["BEGIN:VALARM", "ACTION:DISPLAY", f"DESCRIPTION:{escape(summary)}",
+            f"TRIGGER:{duration(-ahead)}", "END:VALARM"]
+
+
+def ics(entries: list[dict], opts: dict, task_url, now: datetime.datetime | None = None) -> str:
+    """The calendar of ENTRIES (api.calendar): open tasks and events, no
+    habits; TASK_URL(id) is the link each event carries."""
+    stamp_now = (now or datetime.datetime.now(datetime.UTC)).strftime("%Y%m%dT%H%M%SZ")
+    lines = ["BEGIN:VCALENDAR", "VERSION:2.0", "PRODID:-//orgwarrior-web//EN",
+             "CALSCALE:GREGORIAN", "X-WR-CALNAME:orgwarrior",
+             "REFRESH-INTERVAL;VALUE=DURATION:PT1H", "X-PUBLISHED-TTL:PT1H"]
+    for e in entries:
+        if e["habit"] or e["done"]:
+            continue
+        summary = f"{e['keyword']} {e['title']}" if opts["keywords"] and e["keyword"] else e["title"]
+        url = task_url(e["id"])
+        common = [f"URL:{url}", f"DESCRIPTION:{escape(url)}"]
+        if e["tags"]:
+            common.append("CATEGORIES:" + ",".join(escape(t) for t in e["tags"]))
+        n = 0
+        for stamp in e["stamps"]:
+            kind = stamp["kind"]
+            if kind == "deadline" and not opts["deadlines"]:
+                continue
+            if kind not in ("scheduled", "deadline"):
+                n += 1
+            # Stable across fetches, so a calendar updates an event in place.
+            uid = f"{e['id']}-{kind if kind in ('scheduled', 'deadline') else f'{kind}{n}'}"
+            if "dates" in stamp:  # a diary sexp, one event per day it holds
+                for d in stamp["dates"]:
+                    lines += ["BEGIN:VEVENT", f"UID:{uid}-{ical_date(d['date'])}@orgwarrior",
+                              f"DTSTAMP:{stamp_now}", f"DTSTART;VALUE=DATE:{ical_date(d['date'])}",
+                              f"DTEND;VALUE=DATE:{ical_date(next_day(d['date']))}",
+                              f"SUMMARY:{escape(d['text'] or summary)}", *common, "END:VEVENT"]
+                continue
+            # A deadline and a scheduled date would otherwise read the same.
+            title = opts["deadline_prefix"] + summary if kind == "deadline" else summary
+            lines += ["BEGIN:VEVENT", f"UID:{uid}@orgwarrior", f"DTSTAMP:{stamp_now}",
+                      *times(stamp), f"SUMMARY:{escape(title)}", *common]
+            if r := stamp["repeat"]:
+                # .+ and ++ have no iCalendar equivalent: a plain repeat
+                # from the current date, which moves when it's done.
+                lines.append(f"RRULE:FREQ={FREQ[r['unit']]};INTERVAL={r['value']}")
+            lines += [*alarm(stamp, opts, title), "END:VEVENT"]
+    lines.append("END:VCALENDAR")
+    return "".join(fold(line) + "\r\n" for line in lines)

orgwarrior_web/jsonfile.py

@@ -0,0 +1,37 @@
+"""A small JSON state file, beside tokens.json: reread when it changes on
+disk (another process saved it), written atomically."""
+
+import json
+import os
+from pathlib import Path
+
+
+class JsonFile:
+    """PATH's JSON, EMPTY() while there's no file.  MODE, if given, is the
+    new file's permissions (0o600 for secrets)."""
+
+    def __init__(self, path: Path, empty, mode: int | None = None):
+        self.path, self._empty, self._mode = path, empty, mode
+        self._stamp, self._data = None, empty()
+
+    def load(self):
+        try:
+            st = self.path.stat()
+        except FileNotFoundError:
+            self._stamp, self._data = None, self._empty()
+            return self._data
+        if (stamp := (st.st_mtime_ns, st.st_size, st.st_ino)) != self._stamp:
+            self._data = json.loads(self.path.read_text())
+            self._stamp = stamp
+        return self._data
+
+    def save(self, data):
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self.path.with_suffix(".tmp")
+        if self._mode is None:
+            tmp.write_text(json.dumps(data, indent=1))
+        else:
+            fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, self._mode)
+            with os.fdopen(fd, "w") as f:
+                json.dump(data, f, indent=1)
+        os.replace(tmp, self.path)  # atomic: a reader never sees half a file

orgwarrior_web/keymap.py

@@ -0,0 +1,321 @@
+"""The page's keys: every action it has a key for, org agenda's keys for
+them (the defaults), the presets, and `[web.keys]` on top.
+
+One table: the page dispatches on action names, draws its hints and `?`
+from it, and the server checks the config against it at startup, so a
+typo stops the server instead of leaving a key that does nothing.
+
+Keys are written as Emacs writes them (`kbd`): `t`, `T`, `C-k`, `M-<down>`,
+`M-S-<left>`, `RET`, `SPC`, `<prior>`; a sequence is its keys apart, `d d`
+or `C-c C-s`, and a word of plain characters is one key a character (`dd`
+is `d d`, as in Emacs).  What's fixed is left out: Esc and Tab, the keys
+inside sheets and pickers (org's fast keys, the arrows, y and n), Enter
+in a field, Ctrl-Enter; `FIXED` lists them for `?`.
+"""
+
+import re
+from dataclasses import dataclass
+
+
+class KeysError(ValueError):
+    """A key or [web.keys] entry that can't be used; the message says why."""
+
+
+@dataclass(frozen=True)
+class Action:
+    name: str
+    group: str
+    keys: tuple[str, ...]  # org agenda's, the default
+    what: str
+
+
+def _a(name, group, keys, what):
+    return Action(name, group, tuple(keys), what)
+
+
+# In the order `?` lists them.  The defaults are org agenda's keys where they
+# fit; where the page's matter more it differs on purpose (docs/keys.md's
+# list): s d schedule and deadline (org's save, day view), w refile (week
+# view), j k (go to date), r rename (redo; g still), c a A adding (calendar,
+# archive, append), i o now and I O asking (org's I O are now), J K H L
+# moving (org agenda can't move subtrees), e edit and E effort (org's e
+# effort, E entry text).
+ACTIONS = [
+    _a("down", "Moving", ["j", "n", "<down>"], "the next row (side by side: shown beside)"),
+    _a("up", "Moving", ["k", "p", "<up>"], "the row before"),
+    _a("open", "Moving", ["RET"], "open the row"),
+    _a("quit", "Moving", ["q"], "close the task, else back (Esc too, always)"),
+    _a("back", "Moving", ["["], "back through what was shown (Alt-← too)"),
+    _a("forward", "Moving", ["]"], "forward again (Alt-→ too)"),
+    _a("state", "The task", ["t"], "state"),
+    _a("priority", "The task", [","], "priority"),
+    _a("priority-up", "The task", ["S-<up>"], "priority up a step"),
+    _a("priority-down", "The task", ["S-<down>"], "priority down a step"),
+    _a("tags", "The task", [":"], "tags"),
+    _a("schedule", "The task", ["s"], "schedule"),
+    _a("deadline", "The task", ["d"], "deadline"),
+    _a("effort", "The task", ["E"], "effort: the estimate, clocked time shown against it"),
+    _a("note", "The task", ["z"], "add a note"),
+    _a("history", "The task", ["Z"], "its notes and history: change or delete one"),
+    _a("properties", "The task", ["C"], "its properties: change, delete or add one"),
+    _a("outline", "The task", ["h"], "zoom into it: its file's tree from there down, as org's narrowing"),
+    _a("rename", "The task", ["r"], "rename"),
+    _a("edit", "The task", ["e"], "edit its text"),
+    _a("read", "The task", ["V"], "read its text full screen"),
+    _a("refile", "The task", ["w"], "refile (type to filter)"),
+    _a("archive", "The task", ["$"], "archive (asks first)"),
+    _a("kill", "The task", ["C-k"], "kill (asks first)"),
+    _a("move", "Moving it", ["v"], "move: a sheet of ▲ ▼ ◀ ▶"),
+    _a("move-down", "Moving it", ["J", "M-<down>"], "down past the next heading"),
+    _a("move-up", "Moving it", ["K", "M-<up>"], "up past the one before"),
+    _a("promote", "Moving it", ["H", "M-S-<left>"], "out of its parent"),
+    _a("demote", "Moving it", ["L", "M-S-<right>"], "into the heading above"),
+    _a("clock-in", "Clocking", ["i"], "clock in now"),
+    _a("clock-in-at", "Clocking", ["I"], "clock in at a time"),
+    _a("clock-out", "Clocking", ["o"], "clock out now (the clock running, wherever it is)"),
+    _a("clock-out-at", "Clocking", ["O"], "clock out at a time"),
+    _a("clock-cancel", "Clocking", ["X"], "discard the running clock (asks first)"),
+    _a("clock-goto", "Clocking", [], "open the task clocked in"),
+    _a("clocks", "Clocking", ["l"], "the task's clocks: change or delete one"),
+    _a("clock-report", "Clocking", ["R"], "under a day's or week's agenda: what was clocked, on or off"),
+    _a("mark", "Marks", ["m"], "mark, moving down; actions go to the marked"),
+    _a("unmark", "Marks", ["u"], "unmark, moving down"),
+    _a("mark-toggle", "Marks", ["M-m"], "mark or unmark, moving down"),
+    _a("mark-range", "Marks", ["M"], "mark from the last mark to here: a range"),
+    _a("mark-all", "Marks", ["*"], "mark all"),
+    _a("unmark-all", "Marks", ["U"], "unmark all"),
+    _a("add", "Adding", ["c"], "add by keys: a card, then each field by its key, Enter adds"),
+    _a("add-under", "Adding", ["a"], "the same card, the new task under this one"),
+    _a("add-beside", "Adding", ["A"], "the same card, the new task beside this one"),
+    _a("earlier", "Views", ["b"], "a day's agenda: the day before; a week's: the week before"),
+    _a("later", "Views", ["f"], "the day after (a week's: the week after)"),
+    _a("earlier-week", "Views", ["B"], "a day's agenda: a week back"),
+    _a("later-week", "Views", ["F"], "a day's agenda: a week on"),
+    _a("today", "Views", ["."], "today (on a week's agenda, this week)"),
+    _a("date", "Views", ["D"], "a day's or week's agenda: pick the date"),
+    _a("widen", "Views", ["^"], "out of a zoom (h), a level up"),
+    _a("refresh", "Views", ["g"], "refresh"),
+    _a("save-tab", "Views", ["T"], "this view as a tab; on a saved tab, rename, move or remove it"),
+    *[_a(f"tab-{n}", "Views", [str(n % 10)], f"the {n}{'st' if n == 1 else 'nd' if n == 2 else 'rd' if n == 3 else 'th'} tab")
+      for n in range(1, 11)],
+    _a("box", "The page", ["/"], "the box: a view, a search, any orgwarrior command"),
+    _a("command", "The page", ["x"], "the box, for this task (or the marked): done, sched mon…"),
+    _a("help", "The page", ["?"], "this list"),
+    _a("preferences", "The page", ["P"], "preferences: theme, light or dark, key hints"),
+]
+BY_NAME = {a.name: a for a in ACTIONS}
+
+# Always these, whatever the table says (shown by `?` after the actions).
+FIXED = [
+    ("ESC", "cancel, close: a field, a sheet, a form, the open task, the cursor"),
+    ("TAB", "in a file: fold or unfold; in an agenda: the task in its file"),
+    ("S-TAB", "in a file: fold or unfold everything"),
+    ("← → ↑ ↓, h l k j", "between choices in a sheet"),
+    ("a letter, SPC", "in a picker: that choice (org's fast keys); none"),
+    ("y / n", "yes or no, in a question"),
+    ("C-RET", "save the form or sheet you're in"),
+    ("help", "in the box (/): every command it takes, help dates for one"),
+]
+
+# A preset: action -> its keys, replacing that action's defaults ([]: none);
+# the rest keep theirs.  Each says where its keys come from.
+PRESETS = {
+    # evil-collection's org-agenda map (modes/org-agenda/evil-collection-org-agenda.el,
+    # evil-collection 2026-09-27; its theme keys from evil-collection.el's
+    # table), for every action the page has.  An action it has no key for
+    # keeps the page's, unless evil-collection uses that key itself (alone or
+    # as the start of a sequence); then org's own key for it, else none.  Two
+    # from vim: : and / open the box, C-o and C-i go back and forward (vim's
+    # jump list: evil-collection's [[ and ]] jump between blocks).
+    "evil": {
+        "down": ["j", "g j", "C-j", "<down>"],   # org-agenda-next-line; next-item (gj, C-j)
+        "up": ["k", "g k", "C-k", "<up>"],       # org-agenda-previous-line; previous-item
+        "quit": ["q", "Z Z", "Z Q", "x"],        # org-agenda-quit (q, ZZ); -exit (ZQ, x)
+        "back": ["C-o"],                         # vim's jump list
+        "forward": ["C-i"],
+        "priority": ["p"],                       # org-agenda-priority
+        "tags": ["T"],                           # org-agenda-set-tags
+        "schedule": ["s"],                       # org-agenda-schedule
+        "deadline": ["D"],                       # org-agenda-deadline
+        "note": ["n"],                           # org-agenda-add-note
+        "history": [],                           # Z starts its Z Z, Z Q
+        "rename": ["R"],                         # its rename key in other modes (r R): r is refile here
+        "refile": ["r"],                         # org-agenda-refile
+        "archive": ["A"],                        # org-agenda-archive
+        "kill": ["d"],                           # org-agenda-kill (its delete key; asks first)
+        "move": [],                              # v starts its v d, v w, v m, v y
+        "move-down": ["M-<down>"],               # org's: J is its go to date
+        "move-up": ["M-<up>"],                   # org's (K dropped too, to keep the pair)
+        "promote": ["M-S-<left>"],               # org's: H is its earlier
+        "demote": ["M-S-<right>"],               # org's: L is its later
+        "clock-in": ["I"],                       # org-agenda-clock-in
+        "clock-in-at": [],                       # I clocks in now: the toast's Adjust instead
+        "clock-out": ["O", "o"],                 # org-agenda-clock-out
+        "clock-out-at": [],                      # O clocks out now: the toast's Adjust instead
+        "clock-cancel": ["X"],                   # org-agenda-clock-cancel
+        "clock-goto": ["g J"],                   # org-agenda-clock-goto
+        "clock-report": [],                      # R is rename (above)
+        "add-beside": [],                        # A is its archive
+        "earlier": ["H"],                        # org-agenda-earlier
+        "later": ["L"],                          # org-agenda-later
+        "earlier-week": [],                      # B is its bulk action
+        "later-week": [],                        # F is its filters off
+        "date": ["J"],                           # org-agenda-goto-date (its jump key)
+        "refresh": ["g r", "g R"],               # org-agenda-redo, -redo-all
+        "save-tab": [],                          # T is its tags
+        "box": ["/", ":"],                       # vim's search and command line
+        "command": ["B"],                        # org-agenda-bulk-action: the box, for the marked
+    },
+}
+
+# What evil-collection binds that the page has nothing for (docs/keys.md, `?`'s note).
+EVIL_UNMATCHED = ("SPC (show the entry), S (save all), v d v w v m v y (day, week, month, year view), "
+                  "f F (filter by tag, filters off), S-RET g o (open a link), [[ ]] (between blocks)")
+
+
+# ---- Key syntax: Emacs's kbd, written back in one canonical form ----
+
+NAMED = {"RET": "RET", "<return>": "RET", "SPC": "SPC", "TAB": "TAB", "<tab>": "TAB",
+         "ESC": "ESC", "<escape>": "ESC", "DEL": "DEL", "<backspace>": "DEL",
+         "<delete>": "<delete>", "<insert>": "<insert>", "<home>": "<home>", "<end>": "<end>",
+         "<prior>": "<prior>", "<pageup>": "<prior>", "<next>": "<next>", "<pagedown>": "<next>",
+         **{f"<{d}>": f"<{d}>" for d in ("up", "down", "left", "right")},
+         **{f"<f{n}>": f"<f{n}>" for n in range(1, 13)}}
+MODS = {"C": "C-", "M": "M-", "S": "S-", "s": "s-"}
+MOD_ORDER = "CMSs"  # Emacs's order: C-M-S-s-
+
+# Keys the browser keeps (a page can't stop them) and the page's own.
+BROWSER_KEEPS = {"C-n", "C-t", "C-w", "C-q", "C-S-n", "C-S-t", "C-S-w", "C-S-q", "C-TAB", "C-S-TAB",
+                 "C-<prior>", "C-<next>", "s-q", "s-w", "s-t", "s-n", "M-<f4>"}
+PAGE_KEEPS = {"ESC", "TAB", "S-TAB"}
+
+
+def parse_key(word: str) -> str:
+    """One key (`C-k`, `M-S-<left>`, `T`) in its canonical form."""
+    mods, rest = set(), word
+    while len(rest) > 2 and rest[1] == "-" and rest[0] in MODS:
+        if rest[0] in mods:
+            raise KeysError(f"{word!r}: {rest[0]}- twice")
+        mods.add(rest[0])
+        rest = rest[2:]
+    if rest in NAMED:
+        base = NAMED[rest]
+    elif len(rest) == 1 and rest.isprintable() and rest != " ":
+        base = rest
+        # A letter with C- or M- is the key, Shift apart (M-H is M-S-h); a
+        # character alone is as typed (T, $), S- with one folded into it.
+        if rest.isalpha() and rest.isupper() and mods & {"C", "M", "s"}:
+            base, mods = rest.lower(), mods | {"S"}
+        elif "S" in mods and not mods & {"C", "M", "s"}:
+            if not rest.isalpha():
+                raise KeysError(f"{word!r}: write the character Shift makes, not S-")
+            base, mods = rest.upper(), mods - {"S"}
+    else:
+        raise KeysError(f"{word!r} isn't a key: a character, RET SPC TAB ESC DEL, or <down> <f5>…, "
+                        "after C- M- S- s- if any")
+    return "".join(MODS[m] for m in MOD_ORDER if m in mods) + base
+
+
+def parse_sequence(spec: str) -> str:
+    """A key or a sequence (`d d`, `dd`, `C-c C-s`), canonical: its keys apart."""
+    words = spec.split()
+    if not words:
+        raise KeysError("an empty key")
+    keys = []
+    for w in words:
+        # A word of plain characters is one key a character, as kbd reads it.
+        if w not in NAMED and not re.match(r"^([CMSs]-)+.", w) and len(w) > 1 and not w.startswith("<"):
+            keys.extend(parse_key(c) for c in w)
+        else:
+            keys.append(parse_key(w))
+    seq = " ".join(keys)
+    for i, k in enumerate(keys):
+        if k in PAGE_KEEPS:
+            raise KeysError(f"{spec!r}: {k} is the page's own (Esc always cancels, Tab moves and folds)")
+        if k in BROWSER_KEEPS:
+            raise KeysError(f"{spec!r}: the browser keeps {k}; a page can't have it")
+    if len(keys) > 3:
+        raise KeysError(f"{spec!r}: three keys at most")
+    return seq
+
+
+def _keys_of(value, where: str) -> list[str]:
+    """A config value, one key (a string) or several (a list; [] for none), as sequences."""
+    if isinstance(value, str):
+        specs = [value] if value.strip() else []
+    elif isinstance(value, list) and all(isinstance(v, str) for v in value):
+        specs = value
+    else:
+        raise KeysError(f'{where}: a key ("t"), or a list of them (["t", "C-c C-t"]; [] for none)')
+    try:
+        return list(dict.fromkeys(parse_sequence(s) for s in specs))
+    except KeysError as e:
+        raise KeysError(f"{where}: {e}") from None
+
+
+def _layer(table: dict, where: str) -> dict[str, list[str]]:
+    """TABLE (action -> keys), checked: known actions, real keys, no key twice."""
+    out, seen = {}, {}
+    for name, value in table.items():
+        if name not in BY_NAME:
+            near = [a for a in BY_NAME if a.startswith(name[:3])][:3]
+            raise KeysError(f"{where}: no action {name!r}" + (f" (there's {', '.join(near)})" if near else ""))
+        keys = _keys_of(value, f"{where} {name}")
+        for i, k in enumerate(keys):
+            for o in keys[i + 1:]:
+                if _clashes(k, o):
+                    raise KeysError(f"{where} {name}: {k!r} and {o!r}: one starts the other")
+        for k in keys:
+            for other, theirs in seen.items():
+                for o in theirs:
+                    if o == k or o.startswith(k + " ") or k.startswith(o + " "):
+                        raise KeysError(f"{where}: {k!r} ({name}) and {o!r} ({other}): "
+                                        + ("one key, two actions" if o == k else "one starts the other"))
+        seen[name] = keys
+        out[name] = keys
+    return out
+
+
+def _clashes(a: str, b: str) -> bool:
+    return a == b or a.startswith(b + " ") or b.startswith(a + " ")
+
+
+def resolve(config: dict | None) -> dict:
+    """The keys in effect: the defaults, then the preset, then the config's
+    own ([web.keys]), each later one taking its keys from the earlier ones
+    (a key, or the start of a sequence, the later one uses).  For the page:
+    {"preset", "actions": [{name, group, what, keys, org}]}, keys and org
+    (the defaults, for `?` to mark what's changed) as canonical sequences."""
+    config = dict(config or {})
+    preset = config.pop("preset", None)
+    if preset is not None and preset not in PRESETS:
+        raise KeysError(f"[web.keys] preset: {preset!r} isn't one ({', '.join(PRESETS)})")
+    keys = {a.name: [parse_sequence(k) for k in a.keys] for a in ACTIONS}
+    layers = ([(_layer(PRESETS[preset], f"preset {preset}"), f"preset {preset}")] if preset else []) \
+        + [(_layer(config, "[web.keys]"), "[web.keys]")]
+    for layer, _ in layers:
+        taken = [k for ks in layer.values() for k in ks]
+        for name in keys:
+            if name not in layer:
+                keys[name] = [k for k in keys[name] if not any(_clashes(k, t) for t in taken)]
+        keys.update(layer)
+    return {"preset": preset,
+            "actions": [{"name": a.name, "group": a.group, "what": a.what, "keys": keys[a.name],
+                         "org": [parse_sequence(k) for k in a.keys]} for a in ACTIONS],
+            "fixed": FIXED,
+            **({"unmatched": EVIL_UNMATCHED} if preset == "evil" else {})}
+
+
+def readme_table() -> str:
+    """docs/keys.md's table of actions: `python -m orgwarrior_web.keymap`
+    prints it, and a test keeps the page's in step."""
+    org, evil = resolve({}), {a["name"]: a["keys"] for a in resolve({"preset": "evil"})["actions"]}
+    cell = lambda ks: ", ".join(f"`{k}`" for k in ks) or "–"
+    rows = ["| action | org (default) | evil | what it does |", "|---|---|---|---|"]
+    rows += [f"| `{a['name']}` | {cell(a['keys'])} | {cell(evil[a['name']])} | {a['what'].replace('|', '\\|')} |"
+             for a in org["actions"]]
+    return "\n".join(rows)
+
+
+if __name__ == "__main__":
+    print(readme_table())