Implement declarative ManageSieve synchronization CLI #1

Open
opened 2026-11-19 10:43:30 +01:00 by André Keller · 0 comments
Owner

Goal

Implement sievectl, a small command-line tool for managing Sieve filters stored in Git (for example, in dotfiles) and deploying them to ManageSieve accounts. Synchronization is strictly one-way: local files are authoritative. Common uses are vacation replies and fileinto rules.

Configuration

Use a TOML configuration file, suitable for committing to Git alongside the scripts. Identify accounts directly by their email address, without additional aliases or directory mappings. Use one local Sieve file per account and one managed remote script (default name main). Example:

[accounts."user@example.net"]
server = "mail.example.net"
password_command = ["gopass", "show", "-o", "mail/example.net/user"]

The corresponding local file is user@example.net.sieve next to config.toml. The account key is the ManageSieve username. Allow the managed remote script name to be configured globally, with main as the default; per-account overrides can be considered later if needed. Do not store passwords in configuration.

Commands

  • sievectl status [account]: read-only comparison of local content, remote managed script and active state.
  • sievectl sync [account]: upload only if content differs and activate the managed script if needed.
  • sievectl list [account]: list all remote scripts, showing their active and managed status.
  • sievectl delete <account> <script>: explicitly delete a named unmanaged remote script after confirmation; support --yes for automation. Refuse to delete the managed script. Report server-side restrictions (such as deleting an active script) clearly.

Commands that accept [account] operate on all configured accounts when omitted.

Safety and behavior

  • Never pull remote content into local scripts or overwrite local files.
  • Never automatically delete remote scripts, including unmanaged ones.
  • Preserve other remote scripts and do not change their activation except when sync activates the managed script.
  • status and list must never modify server state.
  • On a new account with a different existing main script, sync should make the intended overwrite clear; include a read-only status for preview.
  • Validate TLS certificates and hostnames; do not silently fall back to plaintext authentication.
  • Run password_command without a shell, capture stdout, and pass credentials directly to the Python ManageSieve library. Do not expose passwords in arguments, logs, or error messages.
  • Fail clearly on authentication, connection, protocol, upload, and activation errors. Do not claim a successful sync if activation fails.
  • Keep the tool minimal: no daemon, remote change history, synchronization database, automatic merging, or built-in Sieve rule generation. Git provides version control.

ManageSieve library and validation

  • Prefer Python sievelib (sievelib.managesieve.Client) instead of python-managesieve.
    It supports the required remote script operations and is also a candidate for a future Postoffice Sieve interface.
  • Use the ManageSieve client directly; do not introduce a dependency on sieve-connect.
  • Treat local .sieve files as opaque text: do not parse, normalize, or regenerate them with sievelib's Sieve parser.
  • Check whether the selected sievelib version provides a suitable CHECKSCRIPT API, and use server-side validation
    when available. Regardless, handle PUTSCRIPT validation failures and display the server's diagnostic response.
  • Verify STARTTLS requirements, certificate-chain validation, and hostname verification with the actual library version.
    Reject plaintext authentication, invalid certificates, and hostname mismatches; never downgrade silently.
  • Check the dependency's availability on target distributions. Ubuntu 26.04 provides python3-sievelib;
    confirm Arch packaging before deciding whether an additional package is necessary.
  • Keep the ManageSieve interaction behind a small wrapper so the client library can be replaced if needed.

Implementation and tests

  • Package as a standalone CLI using pyproject.toml.
  • Add pytest tests with a fake/mock ManageSieve client, requiring no live mail server. Cover unchanged scripts, uploads, activation, remote-only scripts, listing, deletion safeguards, credential command failures, protocol errors, and connection errors. Add TLS failure tests (missing STARTTLS, untrusted certificate, hostname mismatch) and validation-error handling.
  • Document setup, gopass integration, initial deployment, status/list output, and rollback via Git followed by sync.

Out of scope (initial version)

Bidirectional synchronization, multiple managed Sieve files per account, automatic deletion, Sieve rule generation, scheduled execution, and automatic conflict merging.

## Goal Implement `sievectl`, a small command-line tool for managing Sieve filters stored in Git (for example, in dotfiles) and deploying them to ManageSieve accounts. Synchronization is strictly **one-way: local files are authoritative**. Common uses are vacation replies and `fileinto` rules. ## Configuration Use a TOML configuration file, suitable for committing to Git alongside the scripts. Identify accounts directly by their email address, without additional aliases or directory mappings. Use one local Sieve file per account and one managed remote script (default name `main`). Example: ```toml [accounts."user@example.net"] server = "mail.example.net" password_command = ["gopass", "show", "-o", "mail/example.net/user"] ``` The corresponding local file is `user@example.net.sieve` next to `config.toml`. The account key is the ManageSieve username. Allow the managed remote script name to be configured globally, with `main` as the default; per-account overrides can be considered later if needed. Do not store passwords in configuration. ## Commands - `sievectl status [account]`: read-only comparison of local content, remote managed script and active state. - `sievectl sync [account]`: upload only if content differs and activate the managed script if needed. - `sievectl list [account]`: list all remote scripts, showing their active and managed status. - `sievectl delete <account> <script>`: explicitly delete a named unmanaged remote script after confirmation; support `--yes` for automation. Refuse to delete the managed script. Report server-side restrictions (such as deleting an active script) clearly. Commands that accept `[account]` operate on all configured accounts when omitted. ## Safety and behavior - Never pull remote content into local scripts or overwrite local files. - Never automatically delete remote scripts, including unmanaged ones. - Preserve other remote scripts and do not change their activation except when `sync` activates the managed script. - `status` and `list` must never modify server state. - On a new account with a different existing `main` script, `sync` should make the intended overwrite clear; include a read-only `status` for preview. - Validate TLS certificates and hostnames; do not silently fall back to plaintext authentication. - Run `password_command` without a shell, capture stdout, and pass credentials directly to the Python ManageSieve library. Do not expose passwords in arguments, logs, or error messages. - Fail clearly on authentication, connection, protocol, upload, and activation errors. Do not claim a successful sync if activation fails. - Keep the tool minimal: no daemon, remote change history, synchronization database, automatic merging, or built-in Sieve rule generation. Git provides version control. ## ManageSieve library and validation - Prefer Python `sievelib` (`sievelib.managesieve.Client`) instead of `python-managesieve`. It supports the required remote script operations and is also a candidate for a future Postoffice Sieve interface. - Use the ManageSieve client directly; do not introduce a dependency on `sieve-connect`. - Treat local `.sieve` files as opaque text: do not parse, normalize, or regenerate them with `sievelib`'s Sieve parser. - Check whether the selected `sievelib` version provides a suitable `CHECKSCRIPT` API, and use server-side validation when available. Regardless, handle `PUTSCRIPT` validation failures and display the server's diagnostic response. - Verify STARTTLS requirements, certificate-chain validation, and hostname verification with the actual library version. Reject plaintext authentication, invalid certificates, and hostname mismatches; never downgrade silently. - Check the dependency's availability on target distributions. Ubuntu 26.04 provides `python3-sievelib`; confirm Arch packaging before deciding whether an additional package is necessary. - Keep the ManageSieve interaction behind a small wrapper so the client library can be replaced if needed. ## Implementation and tests - Package as a standalone CLI using `pyproject.toml`. - Add pytest tests with a fake/mock ManageSieve client, requiring no live mail server. Cover unchanged scripts, uploads, activation, remote-only scripts, listing, deletion safeguards, credential command failures, protocol errors, and connection errors. Add TLS failure tests (missing STARTTLS, untrusted certificate, hostname mismatch) and validation-error handling. - Document setup, `gopass` integration, initial deployment, status/list output, and rollback via Git followed by `sync`. ## Out of scope (initial version) Bidirectional synchronization, multiple managed Sieve files per account, automatic deletion, Sieve rule generation, scheduled execution, and automatic conflict merging.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
tools/sievectl#1
No description provided.