fastmail-cli: Instructions file for Claude Code

fastmail-cli

A CLI for Fastmail over JMAP (email) and CardDAV (contacts), installed as the fastmail binary, which also serves a GraphQL API as an MCP server over stdio or HTTP. It ships as release tarballs for Linux (x86_64 and aarch64) and Apple silicon macOS, and as a multi-arch container image on GHCR, which the MCP gateway runs as a backend and an updater tracks by its GitHub releases.

Git

• Work in PRs; never push to main. PRs are squashed; merge main into a branch rather than rebasing.
• Never push tags. CI tags and publishes when a release PR merges.
• Commits are signed.

Changelog

CHANGELOG.md is generated by scripts/changelog.py and never edited by hand. Every change adds one fragment under changelog.d/unreleased/<section>/, named <pr>-<slug>.md and holding one - **Lead.** Detail. entry; to correct a note, edit its fragment. just changelog --stdout previews the result. The format is in changelog.d/README.md.

Releasing

just release patch|minor|major (or an exact X.Y.Z) branches from main, bumps Cargo.toml and Cargo.lock, turns the unreleased fragments into the version and opens the release PR; the Release workflow does the same from GitHub. Merging it is the release: CD pushes the vX.Y.Z, vX.Y, vX and latest image tags, then creates the GitHub release with the binaries and the changelog section as notes. The image goes first because consumers poll releases and would pin a version with no image behind it. A push releases only when it changes the version; gh workflow run ci-cd.yml on main retries a release that failed part way.

CI/CD

.github/workflows/ci-cd.yml is one pipeline: CI checks the change and ends in the Checks job, which is the only status the ruleset requires; CD runs on main after Checks passes and ships what CI built. The changes job decides from the diff which domains a change touches, and each CI job runs only for its domain, so a skipped job is expected and passes Checks (a failed or cancelled one fails it). The domains are rust (src/, tests/, templates/, the Cargo files; runs Check), docker (the Linux release binaries and the image: on a pull request when Dockerfile changes, on main whenever rust does, since CD ships them), changelog and workflows (.github/workflows/, .github/actions/; runs actionlint). Changes under .github/, a release, a manual run and the twice-weekly cache-warming schedule run every domain. A pull request diffs against its base; a push to main against the last main commit whose run passed, and runs everything when that commit cannot be found. To add a domain, add an output and its path allowlist to changes, gate the new job on it with a job-level if:, and add the job to the needs of Checks; a new top-level source directory is invisible until it is in an allowlist.