tools(oauth-draft): port Gmail OAuth helpers into framework

[potiuk]

Summary

Ports the three Gmail OAuth scripts that previously lived at airflow-s/airflow-s:tools/gmail/oauth-draft/ into the framework as an installable Python project, mirroring the shape of the generate-cve-json port (#2).

The tool was already largely project-agnostic — the only adopter-specific bit was the default credentials path (~/.config/airflow-s/gmail-oauth.json), a holdover from when the tracker repo was named airflow-s. It now defaults to ~/.config/apache-steward/gmail-oauth.json, aligning with the <project-config>/apache-steward/ submodule convention.

Files added

• tools/gmail/oauth-draft/pyproject.toml — three console scripts (oauth-draft-setup, oauth-draft-create, oauth-draft-mark-read). google-auth-oauthlib is the only runtime dep (used by setup); the other two commands are stdlib-only.
• tools/gmail/oauth-draft/src/oauth_draft/credentials.py — shared Credentials dataclass, locate_credentials resolution, refresh_access_token, so the three commands don't duplicate the OAuth boilerplate.
• tools/gmail/oauth-draft/src/oauth_draft/{setup_creds,create_draft,mark_threads_read}.py — one module per command, each with a thin main(argv) callable used by both the console-script entry point and the test suite.
• tools/gmail/oauth-draft/src/oauth_draft/__init__.py — re-exports the three main functions.
• tools/gmail/oauth-draft/tests/{__init__,test_credentials,test_create_draft,test_mark_threads_read}.py — 22 tests covering credential loading, path resolution, MIME building, the pure thread-header helper, and arg-parsing defaults. No tests hit the Gmail API. The originals carried no tests; this thin set gives the pre-commit pytest hook real coverage.
• tools/gmail/oauth-draft/README.md — Run / Setup / How threading is guaranteed / Test / Lint sections, mirroring the generate-cve-json README. The one-time OAuth setup walkthrough that used to live in the airflow-s oauth-draft/README.md is folded in here.
• tools/gmail/oauth-draft/{.gitignore,uv.lock} — standard.

Files updated

• .pre-commit-config.yaml — added the four oauth-draft-* hooks (ruff-check, ruff-format, mypy, pytest), scoped to ^tools/gmail/oauth-draft/(src|tests|pyproject\.toml).
• tools/gmail/{draft-backends,operations}.md — switched legacy script-path references (tools/gmail/oauth-draft/create_draft.py, setup_credentials.py) to the console-script invocation form (uv run --project <framework>/tools/gmail/oauth-draft oauth-draft-*). Default credentials path updated to ~/.config/apache-steward/gmail-oauth.json.
• .claude/skills/{sync,allocate-cve,import,invalidate}-security-issue/SKILL.md — same default-path update; the sync skill also gets the console-script invocation.

Test plan

• ✅ 22 tests pass against the new suite.
• ✅ All four pre-commit hooks pass (ruff/ruff-format/mypy/pytest) plus the standard repo hooks (doctoc, end-of-file-fixer, etc.).
• ✅ All three console scripts respond to --help correctly.

Coordination

A follow-up PR against airflow-s/airflow-s will delete the local tools/gmail/oauth-draft/ scripts there (they live in the framework now via submodule). Existing airflow-s users with credentials at the old ~/.config/airflow-s/gmail-oauth.json path can either move the file to ~/.config/apache-steward/ or set \$GMAIL_OAUTH_CREDENTIALS — that follow-up PR's body will flag this.

🤖 Generated with Claude Code