fix(gmail): make body truncation hints discoverable

Co-authored-by: clawsweeper[bot] <274271284+clawsweeper[bot]@users.noreply.github.com>

Author: clawsweeper[bot]

docs/commands/gog-gmail-thread-get.md

@@ -28,7 +28,7 @@ gog gmail (mail,email) thread (threads,read) get (info,show) <threadId> [flags]
 | `--enable-commands` | `string` |  | Comma-separated list of enabled command prefixes; dot paths allowed (restricts CLI) |
 | `--enable-commands-exact` | `string` |  | Comma-separated list of exact enabled commands; dot paths allowed and parent commands do not enable children |
 | `-y`<br>`--force`<br>`--assume-yes`<br>`--yes` | `bool` |  | Skip confirmations for destructive commands |
-| `--full` | `bool` |  | Show full message bodies |
+| `--full` | `bool` |  | Show full message bodies without truncation |
 | `--gmail-no-send` | `bool` | false | Block Gmail send operations (agent safety) |
 | `-h`<br>`--help` | `kong.helpFlag` |  | Show context-sensitive help. |
 | `--home` | `string` |  | Override gogcli config/data/state/cache root (equivalent to GOG_HOME) |

internal/cmd/execute_gmail_messages_search_text_test.go

@@ -199,6 +199,86 @@ func TestExecute_GmailMessagesSearch_JSON_IncludeBody(t *testing.T) {
 	}
 }
 
+func TestExecute_GmailMessagesSearch_Text_IncludeBodyTruncationDiscoverable(t *testing.T) {
+	longBody := strings.Repeat("b", 240)
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		path := r.URL.Path
+		switch {
+		case strings.Contains(path, "/users/me/messages") && !strings.Contains(path, "/users/me/messages/"):
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"messages": []map[string]any{
+					{"id": "m1", "threadId": "t1"},
+				},
+			})
+			return
+		case strings.Contains(path, "/users/me/messages/m1"):
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"id":       "m1",
+				"threadId": "t1",
+				"labelIds": []string{"INBOX"},
+				"payload": map[string]any{
+					"mimeType": "text/plain",
+					"headers": []map[string]any{
+						{"name": "From", "value": "Example <no-reply@example.com>"},
+						{"name": "Subject", "value": "Receipt"},
+						{"name": "Date", "value": "Mon, 02 Jan 2006 15:04:05 -0700"},
+					},
+					"body": map[string]any{
+						"data": encodeBase64URL(longBody),
+					},
+				},
+			})
+			return
+		case strings.Contains(path, "/users/me/labels"):
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"labels": []map[string]any{
+					{"id": "INBOX", "name": "INBOX", "type": "system"},
+				},
+			})
+			return
+		default:
+			http.NotFound(w, r)
+			return
+		}
+	}))
+	defer srv.Close()
+
+	svc := newGmailServiceFromServer(t, srv)
+
+	defaultResult := executeWithGmailTestService(
+		t,
+		[]string{"--plain", "--account", "a@b.com", "gmail", "messages", "search", "from:example.com", "--include-body"},
+		svc,
+	)
+	if defaultResult.err != nil {
+		t.Fatalf("Execute: %v\nstderr=%q", defaultResult.err, defaultResult.stderr)
+	}
+	if !strings.Contains(defaultResult.stdout, strings.Repeat("b", 200)+gmailTextTruncationMarker) {
+		t.Fatalf("expected actionable truncation marker, got: %q", defaultResult.stdout)
+	}
+	if strings.Contains(defaultResult.stdout, longBody) {
+		t.Fatalf("expected body to be truncated, got: %q", defaultResult.stdout)
+	}
+
+	fullResult := executeWithGmailTestService(
+		t,
+		[]string{"--plain", "--account", "a@b.com", "gmail", "messages", "search", "from:example.com", "--full"},
+		svc,
+	)
+	if fullResult.err != nil {
+		t.Fatalf("Execute full: %v\nstderr=%q", fullResult.err, fullResult.stderr)
+	}
+	if strings.Contains(fullResult.stdout, "[truncated") {
+		t.Fatalf("expected full output without truncation marker, got: %q", fullResult.stdout)
+	}
+	if !strings.Contains(fullResult.stdout, longBody) {
+		t.Fatalf("expected full body, got: %q", fullResult.stdout)
+	}
+}
+
 func TestExecute_GmailMessagesSearch_AppliesSystemLabelFilters(t *testing.T) {
 	var gotQuery string
 	var gotLabels []string

internal/cmd/execute_gmail_text_test.go

@@ -134,7 +134,7 @@ func TestExecute_GmailThread_Text_FullFlag(t *testing.T) {
 			t.Fatalf("Execute: %v", result.err)
 		}
 
-		if !strings.Contains(result.stdout, "[truncated") {
+		if !strings.Contains(result.stdout, gmailTextTruncationMarker) {
 			t.Fatalf("expected truncated output, got=%q", result.stdout)
 		}
 		if strings.Contains(result.stdout, longBody) {

internal/cmd/gmail_messages.go

@@ -17,6 +17,7 @@ import (
 const (
 	gmailMessageBodyFormatText = "text"
 	gmailMessageBodyFormatHTML = "html"
+	gmailTextTruncationMarker  = "... [truncated; use --full or --json]"
 )
 
 type GmailMessagesCmd struct {
@@ -336,8 +337,5 @@ func truncateRunes(s string, maxLen int) string {
 	if len(runes) <= maxLen {
 		return s
 	}
-	if maxLen <= 3 {
-		return string(runes[:maxLen])
-	}
-	return string(runes[:maxLen-3]) + "..."
+	return string(runes[:maxLen]) + gmailTextTruncationMarker
 }

internal/cmd/gmail_messages_test.go

@@ -16,18 +16,19 @@ import (
 func TestSanitizeMessageBody_TruncateUTF8(t *testing.T) {
 	long := strings.Repeat("€", 210)
 	got := sanitizeMessageBody(long, false)
-	if !strings.HasSuffix(got, "...") {
+	if !strings.HasSuffix(got, gmailTextTruncationMarker) {
 		t.Fatalf("expected truncation suffix, got %q", got)
 	}
-	if len([]rune(got)) != 200 {
-		t.Fatalf("expected 200 runes, got %d", len([]rune(got)))
+	preview := strings.TrimSuffix(got, gmailTextTruncationMarker)
+	if len([]rune(preview)) != 200 {
+		t.Fatalf("expected 200 preview runes, got %d", len([]rune(preview)))
 	}
 }
 
 func TestSanitizeMessageBody_FullSkipsTruncation(t *testing.T) {
 	long := strings.Repeat("€", 210)
 	got := sanitizeMessageBody(long, true)
-	if strings.HasSuffix(got, "...") {
+	if strings.Contains(got, "[truncated") {
 		t.Fatalf("expected no truncation with full=true, got %q", got)
 	}
 	if len([]rune(got)) != 210 {

internal/cmd/gmail_presentation_test.go

@@ -59,7 +59,7 @@ func TestGmailPresentationSchemas(t *testing.T) {
 			t,
 			got,
 			"ID\tTHREAD\tDATE\tFROM\tSUBJECT\tLABELS\tBODY\n"+
-				"m1\t\t\t\t\t\t"+strings.Repeat("x", 197)+"...\n",
+				"m1\t\t\t\t\t\t"+strings.Repeat("x", 200)+gmailTextTruncationMarker+"\n",
 		)
 	})
 

internal/cmd/gmail_thread.go

@@ -25,7 +25,7 @@ type GmailThreadCmd struct {
 type GmailThreadGetCmd struct {
 	ThreadID        string        `arg:"" name:"threadId" help:"Thread ID"`
 	Download        bool          `name:"download" help:"Download attachments"`
-	Full            bool          `name:"full" help:"Show full message bodies"`
+	Full            bool          `name:"full" help:"Show full message bodies without truncation"`
 	SanitizeContent bool          `name:"sanitize-content" aliases:"sanitize,safe" help:"Emit agent-oriented sanitized content: strip HTML, remove HTTP(S) URLs, and omit raw Gmail payloads from JSON"`
 	OutputDir       OutputDirFlag `embed:""`
 }
@@ -130,7 +130,7 @@ func (c *GmailThreadGetCmd) Run(ctx context.Context, flags *RootFlags) error {
 			// Use runes to avoid breaking multi-byte UTF-8 characters
 			runes := []rune(cleanBody)
 			if len(runes) > 500 && !c.Full {
-				cleanBody = string(runes[:500]) + "... [truncated]"
+				cleanBody = string(runes[:500]) + gmailTextTruncationMarker
 			}
 			u.Out().Println(cleanBody)
 			u.Out().Println("")

internal/cmd/help_printer_test.go

@@ -128,15 +128,28 @@ func TestHelpProfileNoColorEnv(t *testing.T) {
 }
 
 func TestHelpProfileAlways(t *testing.T) {
-	orig := os.Getenv("NO_COLOR")
-	t.Cleanup(func() { _ = os.Setenv("NO_COLOR", orig) })
-
-	_ = os.Setenv("NO_COLOR", "")
+	unsetColorEnv(t, "NO_COLOR", "CLICOLOR", "CLICOLOR_FORCE")
 	if got := helpProfile(io.Discard, "always"); got != termenv.TrueColor {
 		t.Fatalf("expected truecolor profile")
 	}
 }
 
+func unsetColorEnv(t *testing.T, keys ...string) {
+	t.Helper()
+	for _, key := range keys {
+		key := key
+		orig, ok := os.LookupEnv(key)
+		t.Cleanup(func() {
+			if ok {
+				_ = os.Setenv(key, orig)
+				return
+			}
+			_ = os.Unsetenv(key)
+		})
+		_ = os.Unsetenv(key)
+	}
+}
+
 func TestHelpOptionsEnv(t *testing.T) {
 	orig := os.Getenv("GOG_HELP")
 	t.Cleanup(func() { _ = os.Setenv("GOG_HELP", orig) })

internal/cmd/schema_test.go

@@ -115,6 +115,51 @@ func TestExecute_SchemaIncludesAutomationContract(t *testing.T) {
 	}
 }
 
+func TestExecute_Schema_GmailTruncationHelp(t *testing.T) {
+	threadDoc := schemaForCommand(t, "gmail thread get")
+	threadFull := schemaFlagByName(t, threadDoc.Command, "full")
+	if threadFull.Help != "Show full message bodies without truncation" {
+		t.Fatalf("thread get --full help = %q", threadFull.Help)
+	}
+
+	messagesDoc := schemaForCommand(t, "gmail messages search")
+	messagesFull := schemaFlagByName(t, messagesDoc.Command, "full")
+	if messagesFull.Help != "Show full message bodies without truncation (implies --include-body)" {
+		t.Fatalf("messages search --full help = %q", messagesFull.Help)
+	}
+	includeBody := schemaFlagByName(t, messagesDoc.Command, "include-body")
+	if includeBody.Help != "Include decoded message body (JSON is full; text output is truncated)" {
+		t.Fatalf("messages search --include-body help = %q", includeBody.Help)
+	}
+}
+
+func schemaForCommand(t *testing.T, command string) schemaDoc {
+	t.Helper()
+	result := executeWithTestRuntime(t, []string{"schema", command}, nil)
+	if result.err != nil {
+		t.Fatalf("Execute schema %q: %v", command, result.err)
+	}
+	var doc schemaDoc
+	if err := json.Unmarshal([]byte(result.stdout), &doc); err != nil {
+		t.Fatalf("decode schema %q: %v", command, err)
+	}
+	if doc.Command == nil {
+		t.Fatalf("schema %q missing command", command)
+	}
+	return doc
+}
+
+func schemaFlagByName(t *testing.T, node *schemaNode, name string) schemaFlag {
+	t.Helper()
+	for _, flag := range node.Flags {
+		if flag.Name == name {
+			return flag
+		}
+	}
+	t.Fatalf("%s missing --%s", node.Path, name)
+	return schemaFlag{}
+}
+
 func TestExecute_SchemaRejectsPlainMode(t *testing.T) {
 	var runErr error
 	errText := captureStderr(t, func() {