fastmail-sieve 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. fastmail_sieve-0.1.0/.gitignore +7 -0
  2. fastmail_sieve-0.1.0/LICENSE +21 -0
  3. fastmail_sieve-0.1.0/NOTICE +46 -0
  4. fastmail_sieve-0.1.0/PKG-INFO +329 -0
  5. fastmail_sieve-0.1.0/README.md +298 -0
  6. fastmail_sieve-0.1.0/pyproject.toml +66 -0
  7. fastmail_sieve-0.1.0/src/fastmail_sieve/__init__.py +0 -0
  8. fastmail_sieve-0.1.0/src/fastmail_sieve/__main__.py +5 -0
  9. fastmail_sieve-0.1.0/src/fastmail_sieve/cli.py +102 -0
  10. fastmail_sieve-0.1.0/src/fastmail_sieve/commands/__init__.py +22 -0
  11. fastmail_sieve-0.1.0/src/fastmail_sieve/commands/_options.py +30 -0
  12. fastmail_sieve-0.1.0/src/fastmail_sieve/commands/assemble.py +27 -0
  13. fastmail_sieve-0.1.0/src/fastmail_sieve/commands/auth.py +154 -0
  14. fastmail_sieve-0.1.0/src/fastmail_sieve/commands/diff.py +30 -0
  15. fastmail_sieve-0.1.0/src/fastmail_sieve/commands/doctor.py +16 -0
  16. fastmail_sieve-0.1.0/src/fastmail_sieve/commands/explain.py +60 -0
  17. fastmail_sieve-0.1.0/src/fastmail_sieve/commands/folders.py +30 -0
  18. fastmail_sieve-0.1.0/src/fastmail_sieve/commands/init.py +95 -0
  19. fastmail_sieve-0.1.0/src/fastmail_sieve/commands/lint.py +42 -0
  20. fastmail_sieve-0.1.0/src/fastmail_sieve/commands/migrate.py +29 -0
  21. fastmail_sieve-0.1.0/src/fastmail_sieve/commands/pull.py +31 -0
  22. fastmail_sieve-0.1.0/src/fastmail_sieve/commands/push.py +52 -0
  23. fastmail_sieve-0.1.0/src/fastmail_sieve/config.py +61 -0
  24. fastmail_sieve-0.1.0/src/fastmail_sieve/doctor.py +101 -0
  25. fastmail_sieve-0.1.0/src/fastmail_sieve/fastmail/__init__.py +0 -0
  26. fastmail_sieve-0.1.0/src/fastmail_sieve/fastmail/auth_discovery.py +100 -0
  27. fastmail_sieve-0.1.0/src/fastmail_sieve/fastmail/auth_input.py +41 -0
  28. fastmail_sieve-0.1.0/src/fastmail_sieve/fastmail/blocks.py +181 -0
  29. fastmail_sieve-0.1.0/src/fastmail_sieve/fastmail/credentials.py +279 -0
  30. fastmail_sieve-0.1.0/src/fastmail_sieve/fastmail/jmap.py +59 -0
  31. fastmail_sieve-0.1.0/src/fastmail_sieve/fastmail/mailboxes.py +107 -0
  32. fastmail_sieve-0.1.0/src/fastmail_sieve/project.py +57 -0
  33. fastmail_sieve-0.1.0/src/fastmail_sieve/remote.py +28 -0
  34. fastmail_sieve-0.1.0/src/fastmail_sieve/sieve/__init__.py +0 -0
  35. fastmail_sieve-0.1.0/src/fastmail_sieve/sieve/format.py +121 -0
  36. fastmail_sieve-0.1.0/src/fastmail_sieve/sieve/lint.py +149 -0
  37. fastmail_sieve-0.1.0/src/fastmail_sieve/sieve/migrate.py +246 -0
  38. fastmail_sieve-0.1.0/src/fastmail_sieve/sieve/report.py +728 -0
  39. fastmail_sieve-0.1.0/src/fastmail_sieve/sieve/script.py +83 -0
  40. fastmail_sieve-0.1.0/src/fastmail_sieve/sieve/variable_docs.py +32 -0
  41. fastmail_sieve-0.1.0/src/fastmail_sieve/sieve/variables.py +205 -0
  42. fastmail_sieve-0.1.0/src/fastmail_sieve/sieve/warnings.py +8 -0
  43. fastmail_sieve-0.1.0/src/fastmail_sieve/sieve/wording.py +339 -0
  44. fastmail_sieve-0.1.0/src/fastmail_sieve/steps.py +225 -0
  45. fastmail_sieve-0.1.0/src/fastmail_sieve/ui/__init__.py +0 -0
  46. fastmail_sieve-0.1.0/src/fastmail_sieve/ui/tables.py +53 -0
  47. fastmail_sieve-0.1.0/tests/__init__.py +0 -0
  48. fastmail_sieve-0.1.0/tests/test_auth.py +144 -0
  49. fastmail_sieve-0.1.0/tests/test_auth_status.py +300 -0
  50. fastmail_sieve-0.1.0/tests/test_blocks.py +307 -0
  51. fastmail_sieve-0.1.0/tests/test_check_sieve.py +94 -0
  52. fastmail_sieve-0.1.0/tests/test_cli.py +155 -0
  53. fastmail_sieve-0.1.0/tests/test_commands.py +332 -0
  54. fastmail_sieve-0.1.0/tests/test_config.py +120 -0
  55. fastmail_sieve-0.1.0/tests/test_credentials.py +213 -0
  56. fastmail_sieve-0.1.0/tests/test_doctor.py +198 -0
  57. fastmail_sieve-0.1.0/tests/test_documented_commands.py +44 -0
  58. fastmail_sieve-0.1.0/tests/test_init.py +251 -0
  59. fastmail_sieve-0.1.0/tests/test_jmap.py +116 -0
  60. fastmail_sieve-0.1.0/tests/test_no_variation_selectors.py +19 -0
  61. fastmail_sieve-0.1.0/tests/test_packaging.py +32 -0
  62. fastmail_sieve-0.1.0/tests/test_remote.py +60 -0
  63. fastmail_sieve-0.1.0/tests/test_sieve_blocks.py +103 -0
  64. fastmail_sieve-0.1.0/tests/test_sieve_folders.py +128 -0
  65. fastmail_sieve-0.1.0/tests/test_sieve_format.py +216 -0
  66. fastmail_sieve-0.1.0/tests/test_sieve_migrate.py +296 -0
  67. fastmail_sieve-0.1.0/tests/test_sieve_push.py +353 -0
  68. fastmail_sieve-0.1.0/tests/test_sieve_report.py +667 -0
  69. fastmail_sieve-0.1.0/tests/test_sieve_variables.py +208 -0
  70. fastmail_sieve-0.1.0/tests/test_sieve_warnings.py +96 -0
  71. fastmail_sieve-0.1.0/tests/test_tables.py +67 -0
@@ -0,0 +1,7 @@
1
+ __pycache__/
2
+ *.pyc
3
+ .venv/
4
+ __pycache__/
5
+ *.pyc
6
+ .venv/
7
+ dist/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Hugo Haas
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,46 @@
1
+ fastmail-sieve
2
+ Copyright (c) 2026 Hugo Haas, released under the MIT license (see LICENSE).
3
+
4
+ This project builds on the work of the following project.
5
+
6
+ Fastmail-Sieve-Sync
7
+ https://github.com/fuyu0425/Fastmail-Sieve-Sync
8
+
9
+ Fastmail-Sieve-Sync showed that Fastmail's private SieveBlocks/get and
10
+ SieveBlocks/set JMAP methods exist and what fields they carry. fastmail-sieve
11
+ reimplements, in its own code and from reading that source, the way it:
12
+
13
+ - reads the six parts of the script (require, start, blocked, middle, rules
14
+ and end) and joins them with newlines into the full script;
15
+ - writes back only the start, middle and end blocks;
16
+ - recognises the "Managed by Sieve Sync" markers around those blocks, leaves
17
+ them as it finds them, and replaces the text between them.
18
+
19
+ Scripts that have no markers get fastmail-sieve's own ("Managed by
20
+ fastmail-sieve") instead. Both styles are recognised so that a script already
21
+ managed with Fastmail-Sieve-Sync keeps working. No source file was copied
22
+ verbatim. The license of Fastmail-Sieve-Sync follows.
23
+
24
+ ----------------------------------------------------------------------------
25
+
26
+ MIT License
27
+
28
+ Copyright (c) 2023 Yu-Fu Fu
29
+
30
+ Permission is hereby granted, free of charge, to any person obtaining a copy
31
+ of this software and associated documentation files (the "Software"), to deal
32
+ in the Software without restriction, including without limitation the rights
33
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
34
+ copies of the Software, and to permit persons to whom the Software is
35
+ furnished to do so, subject to the following conditions:
36
+
37
+ The above copyright notice and this permission notice shall be included in all
38
+ copies or substantial portions of the Software.
39
+
40
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
41
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
42
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
43
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
44
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
45
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
46
+ SOFTWARE.
@@ -0,0 +1,329 @@
1
+ Metadata-Version: 2.5
2
+ Name: fastmail-sieve
3
+ Version: 0.1.0
4
+ Summary: Keep Fastmail Sieve rules in git: lint, explain, migrate and sync. Unofficial.
5
+ Project-URL: Homepage, https://github.com/hugoh/fastmail-sieve
6
+ Project-URL: Issues, https://github.com/hugoh/fastmail-sieve/issues
7
+ Project-URL: Repository, https://github.com/hugoh/fastmail-sieve
8
+ Author: Hugo Haas
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ License-File: NOTICE
12
+ Keywords: email,fastmail,filters,jmap,sieve
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Environment :: Console
15
+ Classifier: Intended Audience :: End Users/Desktop
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3 :: Only
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Topic :: Communications :: Email :: Filters
22
+ Classifier: Topic :: Utilities
23
+ Requires-Python: >=3.11
24
+ Requires-Dist: keyring>=25
25
+ Requires-Dist: rich<15,>=14
26
+ Requires-Dist: sievelib<1.7,>=1.6
27
+ Provides-Extra: auth
28
+ Requires-Dist: browser-cookie3; extra == 'auth'
29
+ Requires-Dist: pycryptodomex; extra == 'auth'
30
+ Description-Content-Type: text/markdown
31
+
32
+ # fastmail-sieve
33
+
34
+ Keep your Fastmail Sieve rules in git, and lint, explain, diff and push them
35
+ from the command line. **Unofficial**: not made or supported by Fastmail, and
36
+ it uses an undocumented Fastmail API that can change without notice (see
37
+ [How it works](#how-it-works)).
38
+
39
+ - **Edit rules as files** in three fragments (`rules/top.sieve`,
40
+ `rules/middle.sieve`, `rules/bottom.sieve`), review them in git, and push
41
+ them to Fastmail.
42
+ - **`lint`** is the one check: format, syntax (including Fastmail's own Sieve
43
+ extensions such as `jmapquery` and `mailboxid`), variables, and that every
44
+ folder id in your rules still exists with the right name. It ends with
45
+ warnings (overlaps, duplicates, disabled rules). `lint --fix` reformats your
46
+ rules.
47
+ - **`explain`** shows your rules and your Fastmail UI rules in plain language,
48
+ the whole script, or its variables.
49
+ - **`migrate`** turns your Fastmail UI rules into custom Sieve rules.
50
+ - **`push`** shows the diff and asks before it changes anything.
51
+
52
+ ## How it works
53
+
54
+ Fastmail builds your Sieve script from several parts: its own generated code
55
+ (spam, blocked senders, your Settings > Filters & Rules), and three places
56
+ for your own code that run before and after those parts. `fastmail-sieve`
57
+ reads the whole script, shows you all of it, and only ever writes those three
58
+ blocks, which are your three fragment files.
59
+
60
+ Each block is wrapped in a pair of marker comments, which must stay where they
61
+ are:
62
+
63
+ ```text
64
+ #### Managed by fastmail-sieve: start ####
65
+ #### Managed by fastmail-sieve: end ####
66
+ ```
67
+
68
+ `init --remote` adds them to a script that has none. A script that was
69
+ managed with [Fastmail-Sieve-Sync](#relationship-to-fastmail-sieve-sync)
70
+ already has its `Managed by Sieve Sync Start` and `End` markers; those are
71
+ recognised too and left as they are.
72
+ `init --remote --convert-markers` replaces them with this tool's own markers,
73
+ after asking: your rules are untouched, but Sieve-Sync no longer recognises the
74
+ blocks, so it is a one-way step.
75
+
76
+ Fastmail has no official API for this. The tool calls the private
77
+ `SieveBlocks/get` and `SieveBlocks/set` JMAP methods that Fastmail's own
78
+ Sieve editor uses, with the token and cookie of a logged-in web session (see
79
+ [Credentials](#credentials)). **That can break at any time** and carries the
80
+ risks described there. `fastmail-sieve doctor` tells you what works for your
81
+ account, and whether Fastmail now advertises an official Sieve API (RFC 9661)
82
+ that this tool could use instead.
83
+
84
+ ## Install
85
+
86
+ ```sh
87
+ uv tool install fastmail-sieve # or: pipx install fastmail-sieve
88
+ uvx fastmail-sieve --help # or run it without installing
89
+ ```
90
+
91
+ Python 3.11 or newer. The optional `auth` extra (`fastmail-sieve[auth]`) is
92
+ only for `auth --discover`. The command is also installed as `fmsieve`.
93
+
94
+ ## Quick start
95
+
96
+ ```sh
97
+ mkdir my-sieve && cd my-sieve
98
+ fastmail-sieve init # rules/, variables.toml, .gitignore
99
+ fastmail-sieve auth # store your token and cookie (see Credentials)
100
+ fastmail-sieve init --remote # once: add the managed blocks to Fastmail
101
+ fastmail-sieve pull # bring Fastmail's current blocks into rules/
102
+ $EDITOR rules/middle.sieve
103
+ fastmail-sieve lint --fix # reformat, then check everything
104
+ fastmail-sieve diff # what a push would change
105
+ fastmail-sieve push # shows the diff, asks, pushes, verifies
106
+ ```
107
+
108
+ ## Commands
109
+
110
+ | Command | Does |
111
+ |---------|------|
112
+ | `init` | Create `rules/`, `variables.toml` and a `.gitignore` line; never overwrites. `--remote` also adds the managed blocks to Fastmail's script (once, asks first); `--convert-markers` also replaces Sieve-Sync's marker comments with this tool's own (one way) |
113
+ | `auth` | Check the token and cookie against Fastmail and store them in the keychain. `auth status` shows which credentials are available and where each comes from |
114
+ | `doctor` | Check the project files, the credentials and what Fastmail lets them do |
115
+ | `pull` | Overwrite the three fragments with Fastmail's managed blocks (commit first: local edits are lost) |
116
+ | `push` | Check everything, show the diff, ask, push the managed blocks, then verify with a fresh pull. `--yes` skips the question |
117
+ | `diff` | Show what a push would change (`+` added, `-` removed) |
118
+ | `assemble` | Print the full script (Fastmail's parts plus your fragments); `--output FILE` writes it |
119
+ | `lint` | The one check, as a checklist that stops at the first failure: format and syntax of your rules, then the assembled script (syntax, markers, variables), the folder stable ids and names, and finally the warnings (overlaps, duplicate or conflicting UI rules, disabled UI rules, stale variable descriptions), which are shown but do not fail. `--fix` reformats your rules first (indentation and `:mailboxid` folder names); `--strict` makes warnings fail; `--offline` skips everything that needs Fastmail; `--from-file FILE` checks a saved script |
120
+ | `explain [TOPIC]` | `rules` (the default): a summary table, then your rules and your UI rules as tables. `script`: the whole script in execution order. `variables`: the script's variables and where they are set and read |
121
+ | `migrate` | Print custom rules equivalent to your enabled Fastmail UI rules |
122
+ | `folders` | List Fastmail folders and their ids (`folders tax` filters by path) |
123
+
124
+ Commands that need the script (`assemble`, `diff`, `explain`, `lint`,
125
+ `migrate`) fetch it themselves; pass `--from-file FILE` to use a
126
+ saved copy with no network. `fastmail-sieve COMMAND --help` lists the options.
127
+
128
+ ## Credentials
129
+
130
+ `fastmail-sieve` needs the **browser session token and cookie** of a logged-in
131
+ Fastmail session. Fastmail has no Sieve scope for API tokens, so a normal API
132
+ token cannot read or write the script (it is enough for folder lookups, see
133
+ below).
134
+
135
+ > **The token and cookie are a full web session.** Whoever has both can act as
136
+ > you in Fastmail: read, send and delete mail, change filters (including
137
+ > forwarding rules) and create API tokens. Treat them like your password.
138
+ > Logging out of that session in Fastmail revokes them. How long a pair lasts is
139
+ > not documented by Fastmail.
140
+
141
+ ### Getting them
142
+
143
+ 1. In a browser signed in to Fastmail, open Settings > Filters & Rules > Edit
144
+ custom Sieve code, and open the developer tools on the Network tab.
145
+ 2. Edit anything in the Sieve box and click Save. Then cancel the edit: do not
146
+ keep it.
147
+ 3. Find the request that appears (a POST to `api.fastmail.com`).
148
+ 4. Either right-click it and choose Copy > Copy as cURL, then run
149
+ `pbpaste | fastmail-sieve auth --stdin` (the command is read from standard
150
+ input, so nothing secret lands in your shell history), or copy the value
151
+ after `Authorization: Bearer` (it starts with `fma1-`) and the `Cookie`
152
+ header and run `fastmail-sieve auth` to paste them into two hidden prompts.
153
+
154
+ `auth` checks the pair against Fastmail and stores it in the keychain (service
155
+ `fastmail-sieve-rules`). Run it again when commands fail with HTTP 401.
156
+
157
+ `fastmail-sieve auth --discover` can look for the cookie for you in the Fastmail
158
+ desktop app and in Safari and Chrome. **It reads data that belongs to other
159
+ apps**: it asks the macOS keychain for the "Fastmail Safe Storage" key and
160
+ decrypts the app's cookie database. It is off by default, needs the `auth`
161
+ extra (`pip install 'fastmail-sieve[auth]'`), and prints what it will read
162
+ before it does.
163
+
164
+ ### Where credentials are read from
165
+
166
+ In this order, the first that has them wins:
167
+
168
+ | Source | How |
169
+ |--------|-----|
170
+ | Environment | `FASTMAIL_SIEVE_TOKEN` and `FASTMAIL_SIEVE_COOKIE` |
171
+ | Helper command | `FASTMAIL_SIEVE_CREDENTIAL_COMMAND` prints JSON on stdout |
172
+ | Keychain | what `fastmail-sieve auth` stored |
173
+
174
+ The helper command lets a secret manager supply the pair so that nothing is
175
+ stored by this tool. It is run without a shell (use `sh -c '...'` for a
176
+ pipeline) and must print `{"token": "fma1-…", "cookie": "…"}`, optionally with
177
+ `"api_token"`. For example, `FASTMAIL_SIEVE_CREDENTIAL_COMMAND='op read
178
+ op://Private/fastmail-sieve/json'`. It is read from your environment only,
179
+ never from a file in the repository.
180
+
181
+ **Optional API token for folder lookups.** A read-only Fastmail API token
182
+ (Settings > Privacy & Security > Connected apps & API tokens, Email scope) in
183
+ `FASTMAIL_API_TOKEN` is used for `folders` and the folder checks in `lint`
184
+ instead of the session pair. It cannot read or write the script.
185
+
186
+ There is no command-line option for a token or cookie, because arguments show
187
+ up in `ps` and in shell history. Secrets are never printed: `doctor` and error
188
+ messages name sources and tiers, not values. Without a keychain (headless
189
+ Linux, CI) use environment variables or the helper command. `lint --offline`
190
+ needs no credentials at all, so run that in CI; pushing from CI is not
191
+ recommended.
192
+
193
+ `fastmail-sieve auth status` shows, without contacting Fastmail, each source in
194
+ the order it is tried (environment, helper command, keychain), what it provides
195
+ and whether it is complete, and which credentials each kind of command would
196
+ use: the script needs the session pair, while `folders` prefers an API token.
197
+ It never prints a value, and it reports a failing helper command or a missing
198
+ keychain as a state instead of stopping.
199
+
200
+ `fastmail-sieve doctor` checks the project files, the credentials, what
201
+ Fastmail lets them do (folders, the script, managed blocks) and whether
202
+ Fastmail advertises an official Sieve API, and says what to fix.
203
+
204
+ ## Starting a project
205
+
206
+ `fastmail-sieve init` creates `rules/top.sieve`, `rules/middle.sieve`,
207
+ `rules/bottom.sieve`, `variables.toml` and a `.gitignore` entry, and never
208
+ overwrites a file. Run `fastmail-sieve init --remote` once to add the three
209
+ managed blocks to Fastmail's script if it has none yet (a one-time write that
210
+ keeps any code already there), then `fastmail-sieve pull`. Commands find the
211
+ project from any subdirectory, or use `-C DIR`. An optional
212
+ `fastmail-sieve.toml` in the project root can set `rules-dir` and
213
+ `variables-file`.
214
+
215
+ ## Reading `explain`
216
+
217
+ Rules are numbered in the order they run: your `top` and `middle` rules, then
218
+ Fastmail's UI rules, then your `bottom` rules. Each section has its own
219
+ heading. Output is coloured on a terminal; `NO_COLOR=1` or `--color never`
220
+ turns it off, and `--width N` sets the table width.
221
+
222
+ | Marker | Meaning |
223
+ |--------|---------|
224
+ | 📌 | Pin (flag) the message |
225
+ | 📁 | Move: file into a folder and stop |
226
+ | 🔖 | Label: copy into a folder and keep going |
227
+ | 🚮 | Trash |
228
+ | 🚫 | Junk / spam |
229
+ | 🛑 | Stop applying further rules |
230
+ | ❗ | Duplicate UI rule, or your rule overlaps a UI rule |
231
+
232
+ In conditions the wording is dim and the values being matched (addresses,
233
+ domains, subjects) are shown at normal brightness; with `explain script`,
234
+ Fastmail's own rules are dim throughout. Variable wording comes from `variables.toml`.
235
+
236
+ ## Folder ids and names
237
+
238
+ Rules file mail with `fileinto :mailboxid "ID" "name"`. The id is what Fastmail
239
+ uses and it survives a folder rename; the name is only a hint, but it has to
240
+ be right for `lint` to pass. In Sieve the name is the folder's path with `.`
241
+ separators and an `INBOX.` prefix: `INBOX.finance.taxes`, and
242
+ `INBOX.Inbox.Shopping` for a folder inside the Inbox. `fastmail-sieve lint --fix`
243
+ writes them that way, and `lint` compares them with the live folders. Look ids
244
+ up with `fastmail-sieve folders`.
245
+
246
+ ## Migrating a UI rule to a custom rule
247
+
248
+ 1. Run `fastmail-sieve migrate` and review the output. It supports UI rules
249
+ that match plain `from` searches and file into one folder, optionally
250
+ skipping the Inbox, pinning and stopping. Anything else is an error
251
+ naming the rule and the reason.
252
+ 2. Paste the rules into a block of `rules/middle.sieve`, then run
253
+ `fastmail-sieve lint --fix`.
254
+ 3. `fastmail-sieve diff`, then `fastmail-sieve push`.
255
+ 4. Disable or delete the UI rule in Fastmail. Until you do, `explain` and
256
+ `lint` flag the overlap.
257
+
258
+ A search that isn't a plain `from` address becomes a `jmapquery` rule that
259
+ reuses the UI rule's exact search, so it matches what the UI rule matches. This
260
+ is the only way to express a contact-card rule. Short searches are one quoted
261
+ line; long ones use a multi-line `text:` block, whose closing `.` must start at
262
+ column 0. Only things with no translation (for example a variable other than
263
+ skip-inbox, pin or stop, or several folders in one rule) are errors.
264
+
265
+ Translation differences: `from:x` in a UI rule is a text search (it also
266
+ matches display names and substrings), while the custom rule matches the
267
+ address exactly (`:domain` for bare domains). Test a sample message in
268
+ Fastmail's Sieve tester.
269
+
270
+ ## Using it in CI or a pre-commit hook
271
+
272
+ `fastmail-sieve lint --offline` (add `--fix` for a pre-commit hook) needs no
273
+ credentials and no network. Everything else talks to Fastmail with a full web
274
+ session, so keep it out of CI (see [Credentials](#credentials)).
275
+
276
+ ## Development
277
+
278
+ ```sh
279
+ uv sync --all-extras
280
+ uv run python -m unittest discover -s tests -t .
281
+ mise run lint # every check, via hk
282
+ mise run package-check # build, twine check, install the wheel in a clean env
283
+ ```
284
+
285
+ Versions come from git tags (`hatch-vcs`), and releases are published to PyPI
286
+ by trusted publishing from CI. The Python is a library of small modules under
287
+ `src/fastmail_sieve/` with one small module per command in `commands/`;
288
+ library code never prints or exits.
289
+
290
+ ## Relationship to Fastmail-Sieve-Sync
291
+
292
+ [Fastmail-Sieve-Sync](https://github.com/fuyu0425/Fastmail-Sieve-Sync) (MIT,
293
+ by Yu-Fu Fu) keeps the managed blocks of your Fastmail Sieve script in sync
294
+ with a file. It is where this project learned that the private `SieveBlocks`
295
+ methods exist and what they carry, and it defined the `Managed by Sieve Sync`
296
+ markers around the managed blocks.
297
+
298
+ **What this project takes from it.** The approach (read and write the script
299
+ through `SieveBlocks`), the idea of marking the managed blocks, and the way the
300
+ blocks are handled. That part is reimplemented in this project's own code,
301
+ written from reading Sieve-Sync's source; no source file was copied verbatim.
302
+ Its license and copyright notice are reproduced in [`NOTICE`](NOTICE).
303
+
304
+ **Why a separate tool rather than a dependency or a fork.**
305
+
306
+ - Sieve-Sync is a command-line tool, not a library, and it is not published on
307
+ PyPI. A package on PyPI cannot depend on a git URL, so depending on it meant
308
+ running it as a subprocess: a temporary config file holding your token, its
309
+ debug output to parse, and a scratch file for the script.
310
+ - The checks and the diff here need the script's parts in memory, and
311
+ `push` verifies the result with a fresh read.
312
+ - The scope is wider than syncing: lint, explain, migrate and folder
313
+ validation.
314
+
315
+ **If you only need to sync a file**, Sieve-Sync is smaller and may be all you
316
+ need. A script that Sieve-Sync manages keeps its markers here, so you can
317
+ switch to this tool and back. A script prepared by this tool has its own
318
+ markers, which Sieve-Sync does not recognise, so do not run both tools on the
319
+ same script. This project is not affiliated with Sieve-Sync or its author.
320
+
321
+ ## Credits and license
322
+
323
+ Sieve parsing uses [sievelib](https://github.com/tonioo/sievelib). The session
324
+ and method-call flow is standard JMAP
325
+ ([RFC 8620](https://www.rfc-editor.org/rfc/rfc8620)). See the previous section
326
+ and [`NOTICE`](NOTICE) for Sieve-Sync.
327
+
328
+ MIT, see `LICENSE` and `NOTICE`. "Fastmail" is a trademark of its owner; this
329
+ project is not affiliated with or endorsed by Fastmail.