Repository navigation
feat(tools/mail-source/imap): land the concrete CLI for the IMAP stub - #1466
Merged
Merged
Conversation
Implements the mail-source contract's IMAP adapter per tools/mail-source/imap/README.md and issue apache#303: six stdlib-only console scripts (list_recent_threads, read_thread, list_drafts, list_sent_since, create_draft, thread_url) with UID-based access, root-Message-ID thread canonicalisation, threading headers per the shared gmail threading rule, and the decline-don't-fake exit-code contract (0/2/3/4) for read-only shared role mailboxes. Tests run against a fake IMAP backend with the same method surface; ruff and strict mypy are clean. The package is registered as a workspace member and the contract's capability-matrix note drops its stub caveat. Generated-by: ZCode (GLM, coding agent) Authored-by: liwenjie200543 <liwenjie200543@users.noreply.github.com>
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Required by the prek uv-lock hook after adding tools/mail-source/imap to [tool.uv.workspace] members. Generated-by: ZCode (GLM, coding agent) Authored-by: liwenjie200543 <liwenjie200543@users.noreply.github.com>
github-actions
Bot
added
the
contract:mail-source
…otocol stubs Clears the CodeQL code-scanning findings on mailbox.py: the _QUOTED pattern was left behind when the unquote() helper went away, and the Protocol methods' bare '...' bodies read as no-effect statements. Generated-by: ZCode (GLM, coding agent) Authored-by: liwenjie200543 <liwenjie200543@users.noreply.github.com>
…otocol stubs Clears the CodeQL code-scanning findings on mailbox.py: the _QUOTED pattern was left behind when the unquote() helper went away, and the Protocol methods' bare '...' bodies read as no-effect statements. Generated-by: ZCode (GLM, coding agent) Authored-by: liwenjie200543 <liwenjie200543@users.noreply.github.com>
Kaap10
approved these changes
Sep 29, 2026
Kaap10
left a comment
Kaap10
left a comment
Contributor
There was a problem hiding this comment.
LGTM! Really clean and thorough implementation of the IMAP adapter (#303).
Appreciate keeping it strictly to the Python stdlib (imaplib / email) without pulling in external dependencies, and supporting IMAP_SOURCE_PASSWORD_FILE so secrets don't leak in ps process lists.
The "decline, don't fake" exit codes and draft-only APPEND behavior align perfectly with the contract.
onlyarnav
added a commit
to liwenjie200543/magpie
that referenced
this pull request
Oct 2, 2026
Resolve workspace member conflict in pyproject.toml after apache#1466. Co-authored-by: Arnav <imarnavpurohit@gmail.com>
onlyarnav
added a commit
to liwenjie200543/magpie
that referenced
this pull request
Oct 2, 2026
Resolve workspace member conflict in pyproject.toml after apache#1466. Co-authored-by: Arnav <imarnavpurohit@gmail.com>
potiuk
added
family:ci
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements the mail-source contract's IMAP adapter per
tools/mail-source/imap/README.md, closing #303.What changed
tools/mail-source/imap/(stdlib only —imaplibemail), registered as a workspace member.imap-source-threads,imap-source-read,imap-source-drafts,imap-source-sent,imap-source-create-draft,imap-source-thread-url.(
thread_id_kind: rfc5322-message-id);create_draftattaches to thechronologically last message on the thread per
tools/gmail/threading.mdand only everAPPENDs — drafts, never sends.0ok,2configurationerror,
3capability declined (e.g. a read-only shared role mailboxwithout a writable Drafts folder — the skill's resolution chain falls
through to the next backend),
4server-side failure.--to/--cc), which resolvessecurity_ccper the contract; the adapter never invents a recipient andnever hardcodes an organization address.
run/test/lint instructions, adopter declaration); the contract's
capability-matrix row drops its stub caveat.
How checked
PYTHONPATH=src;tests python -m pytestintools/mail-source/imap/—24 cases against a fake IMAP backend with the same method surface as the
real client (no network): threading canonicalisation, per-operation
behaviour, drafts/sent declines, APPEND-refusal decline, config parsing,
archive-URL template and
imap://fallback.ruff check+ruff format --check+ strictmypyclean.imap-source-thread-urlend-to-end (template + fallback),config-error path exits 2, connection-refused exits 4.
Gen-AI disclosure
Authored with ZCode (GLM) under
docs/ai-contribution-policy.md;
every line reviewed and the checks above run locally by me before posting.