Skip to content

AGENTS.md

Latest commit

 

History

History
76 lines (63 loc) · 4.08 KB

AGENTS.md

File metadata and controls

76 lines (63 loc) · 4.08 KB

AGENTS.md — MailChimp CLI

Rust CLI (mailchimp) for MailChimp marketing API. JSON-first output, --plain for TSV. Rust 2024 edition.

Quick start (copy/paste)

  • Install: cargo build
  • Test: cargo test
  • Single test: cargo test test_name_substring
  • Lint: cargo clippy --all-targets --all-features -- -D warnings
  • Format check: cargo fmt --check
  • Format: cargo fmt
  • Build release: cargo build --release
  • Run: cargo run -- <subcommand> [flags]

Repo map

src/
├── main.rs              # Entry point, CLI parse, command dispatch, exit codes
├── lib.rs               # Public module exports
├── cli/root.rs          # Clap derive structs, global flags, env var names
├── cli/completions.rs   # Shell completion generation
├── error/types.rs       # MailchimpError enum, exit codes (0-6), error_code strings
├── output/              # OutputMode, JSON (NDJSON lists), TSV renderers
├── utils/mod.rs         # ExecutionContext (from_cli with validation)
├── auth/                # OAuth2, token store (keyring/file), multi-account
├── api/client.rs        # MailchimpClient: HTTP verbs, retry, rate limiting
├── api/rate_limiter.rs  # Governor-based 10 req/sec, burst 3
├── api/types.rs         # Error envelope, rate-limit headers, retry classifier
├── audiences/mod.rs     # List audiences, audience detail, name resolution
├── members/mod.rs       # List/add/update/remove/unsubscribe/search members
├── members/batch.rs     # Batch add/update/tag via CSV/email files
├── tags/mod.rs          # List/add/remove tags, members-by-tag
├── segments/mod.rs      # List/info/create/update/delete segments, segment members
├── campaigns/mod.rs     # List/info/create/content/test/schedule/send/delete campaigns
├── templates/mod.rs     # List/info templates, HTML extraction
├── reports/mod.rs       # Campaign/click/open/growth reports
└── models/              # Transport + output model structs
tests/
├── cli_integration.rs   # E2E tests via assert_cmd + mockito
└── api_client_integration.rs  # HTTP client tests via mockito async
.ralph/specs/            # Feature specs (01-29)
tasks/                   # PRD

Working agreements

  • Verify changes: cargo test && cargo clippy --all-targets --all-features -- -D warnings && cargo fmt --check
  • Prefer targeted tests while iterating: cargo test test_name
  • Before finishing, run the full verification command above.
  • Integration tests use mockito::Server + MAILCHIMP_API_BASE_URL env override.
  • Auth integration tests use MAILCHIMP_TOKEN_STORE_PATH with pre-populated JSON stores.

Guardrails (do not)

  • Do not use unwrap() or expect() in production code — use ? and typed MailchimpError
  • Do not call process::exit() in library code — only in main.rs
  • Do not skip check_write_error() for stdout writes (handles BrokenPipe gracefully)
  • Do not render errors to stdout — errors go to stderr, success to stdout
  • Do not add dependencies without justification

Gotchas

  • Rust 2024 edition: Use if-let chains for collapsible if patterns
  • Exit codes: 0=success, 1=general, 2=auth, 3=invalid args, 4=API, 5=rate limited, 6=network
  • Output: Default JSON, --plain for TSV. Lists emit NDJSON (one JSON object per line)
  • Handler pattern: Each module has build_client(ctx), typed handlers return payload structs with headers()/values()
  • 404 classification: Per-module classifiers inspect error text for "list"/"audience" keywords to disambiguate audience-not-found vs entity-not-found
  • t alias disambiguation: mailchimp t list (no positional) → templates; mailchimp t list <id> → tags
  • OAuth env vars: MAILCHIMP_CLIENT_ID, MAILCHIMP_CLIENT_SECRET required for login flow
  • Test env overrides: MAILCHIMP_TOKEN_STORE_PATH, MAILCHIMP_API_BASE_URL, MAILCHIMP_OAUTH_TOKEN_URL, MAILCHIMP_OAUTH_METADATA_URL, MAILCHIMP_OAUTH_LISTEN_ADDR

Detailed architecture

See agent_docs/architecture.md for full module layout, per-spec patterns, and API method details.