Redact API token from JSON output envelope

AGENTS.md

@@ -1,3 +1,58 @@
-# Tooling Convention
+# AGENTS.md
+
+## Tooling Convention
 
 - Use `uv` directly for Python environment and package tasks; do **not** use `uv pip` or `uv venv`.
+
+## Project Structure
+
+```
+src/fastmail_cli/
+  __init__.py        # Exports main()
+  __main__.py        # python -m fastmail_cli
+  cli.py             # Entry point — promotes FASTMAIL_API_TOKEN env var, calls jmapc.main()
+  jmapc.py           # All CLI commands, argparse setup, JMAP client logic
+```
+
+- **Entry point:** `fastmail-cli <command> [args]` (defined in pyproject.toml `[project.scripts]`)
+- **Single runtime dependency:** `jmapc>=0.2.23`
+
+## Running
+
+```bash
+uv run fastmail-cli help                         # list commands
+uv run fastmail-cli describe email.query         # show command options
+uv run fastmail-cli session.get                  # test auth (needs JMAP_API_TOKEN)
+```
+
+## Output Format
+
+Every command returns a JSON envelope:
+
+```json
+{
+  "ok": true,
+  "command": "email.query",
+  "args": { "host": "...", "api_token": "**REDACTED**", ... },
+  "meta": { "timestamp": "...", "account_id": "...", ... },
+  "data": { ... }
+}
+```
+
+On failure, `"data"` is replaced by `"error"`.
+
+## Security
+
+- **Never log or output API tokens.** The `envelope()` function redacts `api_token` from output automatically via `_sanitize_args()`.
+- Prefer environment variables (`JMAP_API_TOKEN`, `FASTMAIL_API_TOKEN`) over `--api-token` CLI flag — CLI args are visible in process listings.
+- If adding new sensitive fields to connection options, add the key name to `_REDACTED_KEYS` in `jmapc.py`.
+- The CLI is read-only by default. `email.draft` / `email.draft-reply` create drafts but never send. `pipeline.run` uses an allowlist of safe JMAP methods.
+
+## Testing
+
+No automated test suite exists yet. Verify changes manually:
+
+```bash
+uv run fastmail-cli help
+uv run fastmail-cli session.get 2>&1 | python -m json.tool
+```

src/fastmail_cli/jmapc.py

@@ -91,6 +91,18 @@ def http_exit_code(status: int) -> int:
     return 3 if status in (401, 403) else 4
 
 
+_REDACTED_KEYS = frozenset({"api_token"})
+
+
+def _sanitize_args(args: Dict[str, Any]) -> Dict[str, Any]:
+    """Return a copy of *args* with sensitive values redacted."""
+    sanitized = dict(args)
+    for key in _REDACTED_KEYS:
+        if key in sanitized and sanitized[key]:
+            sanitized[key] = "**REDACTED**"
+    return sanitized
+
+
 def envelope(
     ok: bool,
     command: str,
@@ -102,7 +114,7 @@ def envelope(
     out: Dict[str, Any] = {
         "ok": ok,
         "command": command,
-        "args": args,
+        "args": _sanitize_args(args),
         "meta": meta,
     }
     if ok: