feat(gmail): import RFC822 messages

[steipete]

Summary

• add gog gmail import <file|-> for one RFC822/EML message
• expose label, internal-date, spam, and calendar-processing controls from Gmail's import API
• parse message headers during dry-run without touching auth, and preserve readonly/command-policy guards
• document the narrow surface and add generated command, unit, safety-profile, and live-harness coverage

This intentionally does not add IMAP fetching, mailbox synchronization, or bulk migration orchestration.

Closes #956.

Proof

• go test ./internal/cmd -run 'TestGmailImport' -count=1
• make ci
• source-blind CLI behavior validation for help/docs, file/stdin dry-run, varied input, malformed/empty input, readonly, and exact allowlists
• autoreview clean with no accepted/actionable findings

Live Gmail import/readback remains a pre-merge gate; the execution host currently has no authorized test account.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 6, 2026, 10:35 AM ET / 14:35 UTC.

ClawSweeper review

What this changes

Adds gog gmail import <file|-> to import one RFC822/EML message with labels and Gmail import controls, plus safeguards, docs, unit tests, and a live-test harness.

Merge readiness

⚠️ Ready for maintainer review - 3 items remain

Keep this collaborator-authored feature open: current main has no Gmail import command, and the proposed narrow API wrapper is a coherent solution awaiting product acceptance and the PR’s stated live import/readback validation.

Priority: P3
Reviewed head: 1e0aae964b5aada6651410ae38039614e0ae9209
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	The patch is focused, covered by request-level tests, and consistent with established Gmail command safeguards; live validation remains the main confidence-improving step.
Proof confidence	🌊 off-meta tidepool	Not applicable: This collaborator-authored PR is not subject to the external-contributor proof gate, though its own stated live Gmail import/readback check remains useful pre-merge validation.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This collaborator-authored PR is not subject to the external-contributor proof gate, though its own stated live Gmail import/readback check remains useful pre-merge validation.
Evidence reviewed	5 items	Current main lacks this capability: Current main's Gmail command tree includes existing read, organize, and write commands but no import command, so the central requested capability is not already implemented. Focused implementation and safeguards: The PR parses input before dry-run, rejects read-only execution, resolves labels through existing helpers, and uploads RFC822 media through Gmail's import endpoint. Protocol-level coverage: The added unit test checks the upload endpoint, Gmail import options, label resolution, uploaded bytes, JSON result, and read-only and command-allowlist guards.
Findings	None	None.
Security	None	None.

How this fits together

The Gmail CLI turns user input into Gmail API requests while applying dry-run, read-only, and command-policy safeguards. This change adds a single-message mailbox write path that reads RFC822 content and returns the imported message metadata.

flowchart LR
  A[EML file or standard input] --> B[Gmail import command]
  B --> C[Parse headers and build plan]
  C --> D{Dry run or blocked?}
  D -->|yes| E[Safe output or error]
  D -->|no| F[Gmail import API]
  F --> G[Message and thread IDs]

Loading

Decision needed

Question	Recommendation
Should gogcli support single-message RFC822/EML import as a first-class Gmail write command rather than relying on the generic API escape hatch?	Accept the narrow command: Keep the one-message scope and land after a live import/readback confirms the Gmail behavior.

Why: This creates a durable public command and option set; mechanical tests establish the request shape but do not determine whether this specialized workflow belongs in the supported CLI surface.

Before merge

• Resolve merge risk (P1) - The PR’s stated live import/readback check has not yet been shown, so Gmail-side acceptance, classification, and readback behavior remain unverified on an authorized account.
• Complete next step (P2) - No repair lane is appropriate: the remaining work is collaborator product acceptance and optional live-account validation, not a discrete patch defect.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Core implementation and coverage	command +167 lines, unit tests +207 lines	The implementation is paired with focused request-shape and safety coverage rather than adding an untested write path.
Changed surface	13 files, +474/-1	The feature updates implementation, generated docs, safety profiles, and the live-test harness together.

Merge-risk options

Maintainer options:

1. Decide the mitigation before merge
   Retain the focused one-message command, confirm its public CLI contract, and attach redacted live import/readback evidence from a disposable authorized Gmail account before landing.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Technical review

Best possible solution:

Retain the focused one-message command, confirm its public CLI contract, and attach redacted live import/readback evidence from a disposable authorized Gmail account before landing.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this PR adds a new command rather than repairing an existing failing behavior. The included mock-server tests establish the intended request path, while the stated live Gmail check remains to be run.

Is this the best way to solve the issue?

Yes, conditionally: a one-message wrapper over Gmail's import endpoint directly addresses the linked request without adding IMAP fetching, synchronization, or bulk migration behavior, subject to maintainer acceptance of the new command surface.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 27af1477df4a.

Labels

Label changes:

• add P3: This is a bounded additive Gmail CLI feature with no demonstrated regression in current user workflows.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• remove rating: 🦞 diamond lobster: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.

Label justifications:

• P3: This is a bounded additive Gmail CLI feature with no demonstrated regression in current user workflows.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This collaborator-authored PR is not subject to the external-contributor proof gate, though its own stated live Gmail import/readback check remains useful pre-merge validation.

Evidence

What I checked:

• Current main lacks this capability: Current main's Gmail command tree includes existing read, organize, and write commands but no import command, so the central requested capability is not already implemented. (internal/cmd/gmail.go:20, 27af1477df4a)
• Focused implementation and safeguards: The PR parses input before dry-run, rejects read-only execution, resolves labels through existing helpers, and uploads RFC822 media through Gmail's import endpoint. (internal/cmd/gmail_import.go:42, 1e0aae964b5a)
• Protocol-level coverage: The added unit test checks the upload endpoint, Gmail import options, label resolution, uploaded bytes, JSON result, and read-only and command-allowlist guards. (internal/cmd/gmail_import_test.go:99, 1e0aae964b5a)
• Feature-history provenance: Gmail command history is chiefly associated with Peter Steinberger, including first-class reply commands and the current PR's two commits. (internal/cmd/gmail.go:20, ba350d6824ce)
• Live validation remains outstanding: The PR body states that a live Gmail import/readback remains a pre-merge gate because its execution host lacks an authorized test account. (1e0aae964b5a)

Likely related people:

• steipete: Authored the current PR and the dominant share of history across the central Gmail command, compose, label, and live-test paths. (role: feature owner and recent Gmail-area contributor; confidence: high; commits: f6a771abc3f1, ba350d6824ce, 6db9b084fd28; files: internal/cmd/gmail.go, internal/cmd/gmail_import.go, internal/cmd/gmail_compose.go)
• salmonumbrella: Feature history shows repeated contributions to the Gmail command surface, including command ergonomics and message behavior. (role: adjacent Gmail contributor; confidence: medium; commits: 3371e3f3ad6d, 4abcd03da7d8; files: internal/cmd/gmail.go, internal/cmd/gmail_send.go)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Attach redacted live import/readback output from a disposable authorized Gmail account.
• Confirm maintainer acceptance of the new public command and flags.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[steipete]

Live proof executed (orchestrator, 2026-08-06, Peter-approved mailbox):

• Built this PR's exact head and ran a real import round trip against a live Gmail account (service mailbox, approved for this test).
• gog gmail import <file> inserted the synthetic RFC822 message; API returned message ID 19fd78d5f6c20c58.
• Readback via gog --readonly gmail get returned the exact subject gogcli-import-livetest-20260806-pr959.
• Cleanup via gog gmail trash succeeded ("action": "trashed").
• No residual test artifacts remain on the remote host or in the mailbox (message trashed).

Combined with the in-PR gates (focused tests, make ci, exact-head CI green across Linux/Darwin-cgo/Windows/worker, clean autoreview), the live-proof requirement is satisfied. Landing.

[holgergruenhagen]

Thank you so much for implementing this, Peter.
Especially this quickly :)
Really appreciate it! 🙏