feat: implement mail commands (#13)

Port all Gmail commands from gmail-ro under `gro mail`:
- search: Search messages with Gmail query syntax
- read: Read a single message
- thread: Read full conversation thread
- labels: List all labels
- attachments: List and download attachments

Includes all test coverage from gmail-ro with 17 new files
and 1094 lines of code.

Closes #5

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: rianjs

internal/cmd/mail/attachments.go

@@ -0,0 +1,26 @@
+package mail
+
+import (
+	"github.com/spf13/cobra"
+)
+
+func newAttachmentsCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "attachments",
+		Short: "Manage message attachments",
+		Long: `List and download attachments from Gmail messages.
+
+This command group provides read-only access to message attachments.
+Use 'list' to view attachment metadata and 'download' to save files locally.
+
+Examples:
+  gro mail attachments list 18abc123def456
+  gro mail attachments download 18abc123def456 --all
+  gro mail attachments download 18abc123def456 --filename report.pdf`,
+	}
+
+	cmd.AddCommand(newListAttachmentsCommand())
+	cmd.AddCommand(newDownloadAttachmentsCommand())
+
+	return cmd
+}

internal/cmd/mail/attachments_download.go

@@ -0,0 +1,139 @@
+package mail
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/open-cli-collective/google-readonly/internal/gmail"
+	ziputil "github.com/open-cli-collective/google-readonly/internal/zip"
+)
+
+var (
+	downloadFilename string
+	downloadDir      string
+	downloadExtract  bool
+	downloadAll      bool
+)
+
+func newDownloadAttachmentsCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "download <message-id>",
+		Short: "Download attachments from a message",
+		Long: `Download attachments from a Gmail message to local disk.
+
+By default, requires --filename to specify which attachment to download,
+or --all to download all attachments.
+
+Zip files can be automatically extracted with --extract flag.
+
+Examples:
+  gro mail attachments download 18abc123def456 --filename report.pdf
+  gro mail attachments download 18abc123def456 --all
+  gro mail attachments download 18abc123def456 --all --output ~/Downloads
+  gro mail attachments download 18abc123def456 --filename archive.zip --extract`,
+		Args: cobra.ExactArgs(1),
+		RunE: runDownloadAttachments,
+	}
+
+	cmd.Flags().StringVarP(&downloadFilename, "filename", "f", "",
+		"Download only attachment with this filename")
+	cmd.Flags().StringVarP(&downloadDir, "output", "o", ".",
+		"Directory to save attachments")
+	cmd.Flags().BoolVarP(&downloadExtract, "extract", "e", false,
+		"Extract zip files after download")
+	cmd.Flags().BoolVarP(&downloadAll, "all", "a", false,
+		"Download all attachments (required if no --filename specified)")
+
+	return cmd
+}
+
+func runDownloadAttachments(cmd *cobra.Command, args []string) error {
+	if downloadFilename == "" && !downloadAll {
+		return fmt.Errorf("must specify --filename or --all")
+	}
+
+	client, err := newGmailClient()
+	if err != nil {
+		return err
+	}
+
+	messageID := args[0]
+	attachments, err := client.GetAttachments(messageID)
+	if err != nil {
+		return err
+	}
+
+	if len(attachments) == 0 {
+		fmt.Println("No attachments found for message.")
+		return nil
+	}
+
+	// Filter by filename if specified
+	var toDownload []*gmail.Attachment
+	for _, att := range attachments {
+		if downloadFilename == "" || att.Filename == downloadFilename {
+			toDownload = append(toDownload, att)
+		}
+	}
+
+	if len(toDownload) == 0 {
+		return fmt.Errorf("attachment not found: %s", downloadFilename)
+	}
+
+	// Create output directory if needed
+	if err := os.MkdirAll(downloadDir, 0755); err != nil {
+		return fmt.Errorf("failed to create output directory: %w", err)
+	}
+
+	// Download each attachment
+	for _, att := range toDownload {
+		data, err := downloadAttachment(client, messageID, att)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "Error downloading %s: %v\n", att.Filename, err)
+			continue
+		}
+
+		outputPath := filepath.Join(downloadDir, att.Filename)
+		if err := saveAttachment(outputPath, data); err != nil {
+			fmt.Fprintf(os.Stderr, "Error saving %s: %v\n", att.Filename, err)
+			continue
+		}
+
+		fmt.Printf("Downloaded: %s (%s)\n", outputPath, formatSize(int64(len(data))))
+
+		// Extract if zip and --extract flag
+		if downloadExtract && isZipFile(att.Filename, att.MimeType) {
+			extractDir := filepath.Join(downloadDir,
+				strings.TrimSuffix(att.Filename, filepath.Ext(att.Filename)))
+			if err := ziputil.Extract(outputPath, extractDir, ziputil.DefaultOptions()); err != nil {
+				fmt.Fprintf(os.Stderr, "Error extracting %s: %v\n", att.Filename, err)
+			} else {
+				fmt.Printf("Extracted to: %s\n", extractDir)
+			}
+		}
+	}
+
+	return nil
+}
+
+func downloadAttachment(client *gmail.Client, messageID string, att *gmail.Attachment) ([]byte, error) {
+	if att.AttachmentID != "" {
+		return client.DownloadAttachment(messageID, att.AttachmentID)
+	}
+	return client.DownloadInlineAttachment(messageID, att.PartID)
+}
+
+func saveAttachment(path string, data []byte) error {
+	return os.WriteFile(path, data, 0644)
+}
+
+func isZipFile(filename, mimeType string) bool {
+	ext := strings.ToLower(filepath.Ext(filename))
+	return ext == ".zip" ||
+		mimeType == "application/zip" ||
+		mimeType == "application/x-zip-compressed"
+}

internal/cmd/mail/attachments_list.go

@@ -0,0 +1,77 @@
+package mail
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+)
+
+var listAttachmentsJSON bool
+
+func newListAttachmentsCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "list <message-id>",
+		Short: "List attachments in a message",
+		Long: `List all attachments in a Gmail message with their metadata.
+
+Shows filename, MIME type, size, and whether the attachment is inline.
+
+Examples:
+  gro mail attachments list 18abc123def456
+  gro mail attachments list 18abc123def456 --json`,
+		Args: cobra.ExactArgs(1),
+		RunE: runListAttachments,
+	}
+
+	cmd.Flags().BoolVarP(&listAttachmentsJSON, "json", "j", false, "Output as JSON")
+
+	return cmd
+}
+
+func runListAttachments(cmd *cobra.Command, args []string) error {
+	client, err := newGmailClient()
+	if err != nil {
+		return err
+	}
+
+	attachments, err := client.GetAttachments(args[0])
+	if err != nil {
+		return err
+	}
+
+	if len(attachments) == 0 {
+		fmt.Println("No attachments found for message.")
+		return nil
+	}
+
+	if listAttachmentsJSON {
+		return printJSON(attachments)
+	}
+
+	fmt.Printf("Found %d attachment(s):\n\n", len(attachments))
+	for i, att := range attachments {
+		fmt.Printf("%d. %s\n", i+1, att.Filename)
+		fmt.Printf("   Type: %s\n", att.MimeType)
+		fmt.Printf("   Size: %s\n", formatSize(att.Size))
+		if att.IsInline {
+			fmt.Printf("   Inline: yes\n")
+		}
+		fmt.Println()
+	}
+
+	return nil
+}
+
+// formatSize converts bytes to human-readable format
+func formatSize(bytes int64) string {
+	const unit = 1024
+	if bytes < unit {
+		return fmt.Sprintf("%d B", bytes)
+	}
+	div, exp := int64(unit), 0
+	for n := bytes / unit; n >= unit; n /= unit {
+		div *= unit
+		exp++
+	}
+	return fmt.Sprintf("%.1f %cB", float64(bytes)/float64(div), "KMGTPE"[exp])
+}

internal/cmd/mail/attachments_test.go

@@ -0,0 +1,134 @@
+package mail
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestIsZipFile(t *testing.T) {
+	tests := []struct {
+		name     string
+		filename string
+		mimeType string
+		expected bool
+	}{
+		{"zip extension lowercase", "archive.zip", "", true},
+		{"zip extension uppercase", "ARCHIVE.ZIP", "", true},
+		{"zip extension mixed case", "Archive.Zip", "", true},
+		{"application/zip mime type", "archive", "application/zip", true},
+		{"application/x-zip-compressed mime type", "archive", "application/x-zip-compressed", true},
+		{"pdf file", "document.pdf", "application/pdf", false},
+		{"txt file", "readme.txt", "text/plain", false},
+		{"no extension with wrong mime", "archive", "application/octet-stream", false},
+		{"zip extension with different mime", "archive.zip", "application/octet-stream", true},
+		{"empty filename with zip mime", "", "application/zip", true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := isZipFile(tt.filename, tt.mimeType)
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}
+
+func TestFormatSize(t *testing.T) {
+	tests := []struct {
+		name     string
+		bytes    int64
+		expected string
+	}{
+		{"zero bytes", 0, "0 B"},
+		{"small bytes", 500, "500 B"},
+		{"exactly 1KB", 1024, "1.0 KB"},
+		{"1.5 KB", 1536, "1.5 KB"},
+		{"exactly 1MB", 1024 * 1024, "1.0 MB"},
+		{"2.5 MB", 2621440, "2.5 MB"},
+		{"exactly 1GB", 1024 * 1024 * 1024, "1.0 GB"},
+		{"large file", 5368709120, "5.0 GB"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := formatSize(tt.bytes)
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}
+
+func TestAttachmentsCommand(t *testing.T) {
+	cmd := newAttachmentsCommand()
+
+	t.Run("has correct use", func(t *testing.T) {
+		assert.Equal(t, "attachments", cmd.Use)
+	})
+
+	t.Run("has subcommands", func(t *testing.T) {
+		subcommands := cmd.Commands()
+		assert.GreaterOrEqual(t, len(subcommands), 2)
+
+		var names []string
+		for _, cmd := range subcommands {
+			names = append(names, cmd.Name())
+		}
+		assert.Contains(t, names, "list")
+		assert.Contains(t, names, "download")
+	})
+}
+
+func TestListAttachmentsCommand(t *testing.T) {
+	cmd := newListAttachmentsCommand()
+
+	t.Run("has correct use", func(t *testing.T) {
+		assert.Equal(t, "list <message-id>", cmd.Use)
+	})
+
+	t.Run("requires exactly one argument", func(t *testing.T) {
+		err := cmd.Args(cmd, []string{})
+		assert.Error(t, err)
+
+		err = cmd.Args(cmd, []string{"msg123"})
+		assert.NoError(t, err)
+	})
+
+	t.Run("has json flag", func(t *testing.T) {
+		flag := cmd.Flags().Lookup("json")
+		assert.NotNil(t, flag)
+		assert.Equal(t, "j", flag.Shorthand)
+	})
+}
+
+func TestDownloadAttachmentsCommand(t *testing.T) {
+	cmd := newDownloadAttachmentsCommand()
+
+	t.Run("has correct use", func(t *testing.T) {
+		assert.Equal(t, "download <message-id>", cmd.Use)
+	})
+
+	t.Run("requires exactly one argument", func(t *testing.T) {
+		err := cmd.Args(cmd, []string{})
+		assert.Error(t, err)
+
+		err = cmd.Args(cmd, []string{"msg123"})
+		assert.NoError(t, err)
+	})
+
+	t.Run("has required flags", func(t *testing.T) {
+		flags := []struct {
+			name      string
+			shorthand string
+		}{
+			{"filename", "f"},
+			{"output", "o"},
+			{"extract", "e"},
+			{"all", "a"},
+		}
+
+		for _, f := range flags {
+			flag := cmd.Flags().Lookup(f.name)
+			assert.NotNil(t, flag, "flag %s should exist", f.name)
+			assert.Equal(t, f.shorthand, flag.Shorthand, "flag %s should have shorthand %s", f.name, f.shorthand)
+		}
+	})
+}