How mbrt/gmailctl works
Project type and purpose
• gmailctl is a Go‑based command‑line utility (CLI tool) for managing Gmail filters declaratively.
• It defines two executables in cmd/:
• gmailctl – the main CLI (commands: init, edit, diff, apply, download, export, test)
• gmailctl‑config‑migrate – a subtool to convert older YAML filters to the current Jsonnet format
• Core functionality: read a Jsonnet config, build an in‑memory representation of filters+actions, diff vs. remote Gmail settings, and apply changes via Gmail’s REST API.
High‑level file‑structure analysis
• /cmd: entry points; one for the main CLI, one for the migration tool. They parse flags, load config, dispatch to subcommands.
• /internal: core packages, each encapsulating a layer of the pipeline:
• data: default config, static assets (JSONNET libs)
• engine: subpackages implementing all phases
– config: read & validate Jsonnet config (v1alpha1, v1alpha2, v1alpha3 support)
– parser: Jsonnet → AST → internal filters model
– filter & label & gmail & apply & export: build Gmail API calls or XML exports; compute diffs
– cfgtest: run “test” subcommand against synthetic messages
– api: wrap Gmail REST endpoints ( filters, labels )
– rimport: re‑import downloaded XML/JSON into Jsonnet
• localcred: OAuth2 flow / local HTTP server for user consent
• fakegmail: a fake Gmail server for testing
• graph: auxiliary matching algorithms (e.g., for diffing lists)
• reporting, stringset, errors: utility libraries
• Snapcraft, GitHub workflows, integration_test.go – CI, packaging, and E2E tests.
Key architecture insights from README
• Separation of concerns: config reading → rule/model construction → diff/export → apply
• Use of Jsonnet for configuration → requires a parser phase
• Two modes of output: Gmail REST calls (apply) and XML filter export (export)
• Test harness (cfgtest) isolates model from real Gmail API