fix(outfmt): preserve Gmail attachment result envelopes (#943)

Preserve the complete single-object Gmail result envelope when attachment metadata is present, and keep the exact output-shape regression assertion aligned with the seven legitimate fields.

Proof:
- focused Gmail draft regression test passes
- full `make ci` passes
- built `gog` binary reports the exact review head and renders Gmail help successfully
- exact-head GitHub CI, Docker, worker, Windows, and Darwin checks pass

Co-authored-by: hashtag1974 <258647037+hashtag1974@users.noreply.github.com>

Author: hashtag1974

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## 0.34.2 - 2026-07-27
 
+- Gmail: preserve single-object result envelopes for attachment-bearing `--results-only` output. (#943) — thanks @hashtag1974.
 - Sheets: keep positional updates within the requested range, preserving comma-bearing single-cell values and accurate named-range dry runs. (#941) — thanks @cathrynlavery.
 - Gmail: add source-specific `internalDateIso` timestamps to message and thread listings while preserving the legacy sender-header `date`. (#945, #946) — thanks @chrischall.
 - Gmail: prevent standalone draft updates from acquiring self-referential reply headers, with explicit recovery for affected drafts. (#942, #944) — thanks @chrischall.

internal/cmd/gmail_drafts.go

@@ -536,7 +536,7 @@ func writeDraftResult(ctx context.Context, u *ui.UI, draft *gmail.Draft, threadi
 		if len(attachments) > 0 {
 			result["attachments"] = attachments
 		}
-		return outfmt.WriteJSON(ctx, stdoutWriter(ctx), result)
+		return outfmt.WriteJSON(ctx, stdoutWriter(ctx), outfmt.PrimaryResult(result))
 	}
 	u.Out().Linef("draft_id\t%s", draft.Id)
 	if draft.Message != nil && draft.Message.Id != "" {

internal/cmd/gmail_drafts_cmd_test.go

@@ -9,12 +9,14 @@ import (
 	"net/http/httptest"
 	"os"
 	"path/filepath"
+	"reflect"
 	"strings"
 	"testing"
 
 	"google.golang.org/api/gmail/v1"
 
 	"github.com/steipete/gogcli/internal/mailmime"
+	"github.com/steipete/gogcli/internal/outfmt"
 )
 
 type gmailQuoteSource struct {
@@ -324,6 +326,85 @@ func TestGmailDraftsCreateCmd_JSON(t *testing.T) {
 	}
 }
 
+func TestGmailDraftsCreateCmd_JSON_ResultsOnlyPreservesCompleteAttachmentResult(t *testing.T) {
+	attachmentPath := filepath.Join(t.TempDir(), "fixture.txt")
+	if err := os.WriteFile(attachmentPath, []byte("fixture"), 0o600); err != nil {
+		t.Fatalf("write attachment: %v", err)
+	}
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if strings.Contains(r.URL.Path, "/gmail/v1/users/me/drafts") && r.Method == http.MethodPost {
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"id": "d1",
+				"message": map[string]any{
+					"id":       "m1",
+					"threadId": "t1",
+				},
+			})
+			return
+		}
+		http.NotFound(w, r)
+	}))
+	defer srv.Close()
+
+	run := func(resultsOnly bool) []byte {
+		t.Helper()
+		svc := newGmailServiceFromServer(t, srv)
+		flags := &RootFlags{Account: "synthetic@example.com"}
+		var jsonOut bytes.Buffer
+		ctx := withGmailTestService(newCmdRuntimeJSONOutputContext(t, &jsonOut, io.Discard), svc)
+		if resultsOnly {
+			ctx = outfmt.WithJSONTransform(ctx, outfmt.JSONTransform{ResultsOnly: true})
+		}
+		if err := runKong(t, &GmailDraftsCreateCmd{}, []string{
+			"--to", "recipient@example.com",
+			"--subject", "Synthetic subject",
+			"--body", "Synthetic body",
+			"--attach", attachmentPath,
+		}, ctx, flags); err != nil {
+			t.Fatalf("execute: %v", err)
+		}
+		return jsonOut.Bytes()
+	}
+
+	baseline := run(false)
+	got := run(true)
+	var wantValue any
+	if err := json.Unmarshal(baseline, &wantValue); err != nil {
+		t.Fatalf("baseline json parse: %v", err)
+	}
+	var gotValue any
+	if err := json.Unmarshal(got, &gotValue); err != nil {
+		t.Fatalf("results-only json parse: %v", err)
+	}
+	if !reflect.DeepEqual(gotValue, wantValue) {
+		t.Fatalf("--results-only changed the complete Gmail draft-create result:\ngot:\n%s\nwant:\n%s", got, baseline)
+	}
+
+	parsed, ok := gotValue.(map[string]any)
+	if !ok {
+		t.Fatalf("expected complete Gmail draft-create object, got %T: %s", gotValue, got)
+	}
+	expectedKeys := []string{
+		"draftId",
+		"message",
+		"threadId",
+		"attachments",
+		"inReplyTo",
+		"references",
+		"replyContextSource",
+	}
+	for _, key := range expectedKeys {
+		if _, ok := parsed[key]; !ok {
+			t.Fatalf("synthetic pre-transform shape is missing %q: %s", key, got)
+		}
+	}
+	if len(parsed) != len(expectedKeys) {
+		t.Fatalf("unexpected synthetic pre-transform keys: %s", got)
+	}
+}
+
 func TestGmailDraftsCreateCmd_BodyHTMLFile(t *testing.T) {
 	htmlPath := filepath.Join(t.TempDir(), "body.html")
 	if err := os.WriteFile(htmlPath, []byte("<h1>Hello</h1>\n<p>from file</p>"), 0o600); err != nil {

internal/cmd/gmail_get.go

@@ -113,7 +113,7 @@ func (c *GmailGetCmd) Run(ctx context.Context, flags *RootFlags) error {
 				payload["attachments"] = attachmentOutputs(attachments)
 			}
 		}
-		return outfmt.WriteJSON(ctx, stdoutWriter(ctx), payload)
+		return outfmt.WriteJSON(ctx, stdoutWriter(ctx), outfmt.PrimaryResult(payload))
 	}
 
 	u.Out().Linef("id\t%s%s", msg.Id, gmailHumanMessageStatusMarker(ctx, msg.LabelIds))

internal/cmd/gmail_get_cmd_test.go

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
+	"reflect"
 	"strings"
 	"testing"
 )
@@ -271,6 +272,56 @@ func gmailGetAttachmentHandler(subject, body string) http.Handler {
 	})
 }
 
+func TestGmailGetCmd_JSON_ResultsOnlyPreservesCompleteAttachmentResult(t *testing.T) {
+	srv := httptest.NewServer(gmailGetAttachmentHandler("Synthetic attachment", "synthetic body"))
+	defer srv.Close()
+
+	run := func(resultsOnly bool) []byte {
+		t.Helper()
+		args := []string{"--json"}
+		if resultsOnly {
+			args = append(args, "--results-only")
+		}
+		args = append(args,
+			"--account", "synthetic@example.com",
+			"gmail", "get", "m1",
+			"--format", "full",
+		)
+		result := executeWithGmailTestService(t, args, newGmailServiceFromServer(t, srv))
+		if result.err != nil {
+			t.Fatalf("execute: %v\nstderr=%q", result.err, result.stderr)
+		}
+		return []byte(result.stdout)
+	}
+
+	baseline := run(false)
+	got := run(true)
+	var wantValue any
+	if err := json.Unmarshal(baseline, &wantValue); err != nil {
+		t.Fatalf("baseline json parse: %v", err)
+	}
+	var gotValue any
+	if err := json.Unmarshal(got, &gotValue); err != nil {
+		t.Fatalf("results-only json parse: %v", err)
+	}
+	if !reflect.DeepEqual(gotValue, wantValue) {
+		t.Fatalf("--results-only changed the complete Gmail get result:\ngot:\n%s\nwant:\n%s", got, baseline)
+	}
+
+	parsed, ok := gotValue.(map[string]any)
+	if !ok {
+		t.Fatalf("expected complete Gmail get object, got %T: %s", gotValue, got)
+	}
+	for _, key := range []string{"message", "headers", "body", "attachments"} {
+		if _, ok := parsed[key]; !ok {
+			t.Fatalf("synthetic pre-transform shape is missing %q: %s", key, got)
+		}
+	}
+	if len(parsed) != 4 {
+		t.Fatalf("unexpected synthetic pre-transform keys: %s", got)
+	}
+}
+
 func TestGmailGetCmd_Text_Full_WithAttachments(t *testing.T) {
 	srv := httptest.NewServer(gmailGetAttachmentHandler("Test", "hello"))
 	defer srv.Close()

internal/outfmt/outfmt.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"io"
 	"os"
+	"sort"
 	"strconv"
 	"strings"
 )
@@ -71,6 +72,17 @@ type JSONTransform struct {
 
 type jsonTransformKey struct{}
 
+type primaryResult struct {
+	value any
+}
+
+// PrimaryResult marks a complete JSON value as already being the command's
+// primary result. WriteJSON still applies field selection, but --results-only
+// preserves the complete value instead of inferring a nested collection.
+func PrimaryResult(value any) any {
+	return primaryResult{value: value}
+}
+
 func WithJSONTransform(ctx context.Context, t JSONTransform) context.Context {
 	return context.WithValue(ctx, jsonTransformKey{}, t)
 }
@@ -87,7 +99,18 @@ func JSONTransformFromContext(ctx context.Context) (JSONTransform, bool) {
 }
 
 func WriteJSON(ctx context.Context, w io.Writer, v any) error {
+	alreadyPrimary := false
+
+	if result, ok := v.(primaryResult); ok {
+		v = result.value
+		alreadyPrimary = true
+	}
+
 	if t, ok := JSONTransformFromContext(ctx); ok && (t.ResultsOnly || len(t.Select) > 0) {
+		if alreadyPrimary {
+			t.ResultsOnly = false
+		}
+
 		transformed, err := applyJSONTransform(v, t)
 		if err != nil {
 			return fmt.Errorf("transform json: %w", err)
@@ -174,6 +197,8 @@ func unwrapPrimary(v any) any {
 		candidates = append(candidates, k)
 	}
 
+	sort.Strings(candidates)
+
 	if len(candidates) == 1 {
 		return m[candidates[0]]
 	}

internal/outfmt/outfmt_test.go

@@ -127,6 +127,110 @@ func TestWriteJSON_ResultsOnlyDoesNotPreferScalarKnownKeyOverArray(t *testing.T)
 	}
 }
 
+func TestWriteJSON_ResultsOnlyPreservesExplicitPrimaryResult(t *testing.T) {
+	ctx := WithJSONTransform(context.Background(), JSONTransform{ResultsOnly: true})
+	input := map[string]any{
+		"draftId": "d1",
+		"message": map[string]any{
+			"id":       "m1",
+			"threadId": "t1",
+		},
+		"threadId": "t1",
+		"attachments": []map[string]any{{
+			"filename": "fixture.txt",
+			"size":     7,
+		}},
+	}
+
+	var baseline bytes.Buffer
+	if err := WriteJSON(context.Background(), &baseline, input); err != nil {
+		t.Fatalf("WriteJSON baseline: %v", err)
+	}
+
+	var got bytes.Buffer
+	if err := WriteJSON(ctx, &got, PrimaryResult(input)); err != nil {
+		t.Fatalf("WriteJSON primary result: %v", err)
+	}
+
+	if got.String() != baseline.String() {
+		t.Fatalf("complete primary result changed:\ngot:\n%s\nwant:\n%s", got.String(), baseline.String())
+	}
+}
+
+func TestWriteJSON_ResultsOnlyGenericArraySelectionIsDeterministic(t *testing.T) {
+	ctx := WithJSONTransform(context.Background(), JSONTransform{ResultsOnly: true})
+	input := map[string]any{
+		"zItems": []map[string]any{{"id": "z"}},
+		"aItems": []map[string]any{{"id": "a"}},
+	}
+
+	for range 50 {
+		var buf bytes.Buffer
+		if err := WriteJSON(ctx, &buf, input); err != nil {
+			t.Fatalf("WriteJSON: %v", err)
+		}
+
+		var got []map[string]any
+		if err := json.Unmarshal(buf.Bytes(), &got); err != nil {
+			t.Fatalf("unmarshal: %v (out=%q)", err, buf.String())
+		}
+
+		if len(got) != 1 || got[0]["id"] != "a" {
+			t.Fatalf("generic selection was not deterministic: %s", strings.TrimSpace(buf.String()))
+		}
+	}
+}
+
+func TestWriteJSON_ResultsOnlyAttachmentCommandStillReturnsAttachments(t *testing.T) {
+	ctx := WithJSONTransform(context.Background(), JSONTransform{ResultsOnly: true})
+	input := map[string]any{
+		"threadId": "t1",
+		"attachments": []map[string]any{{
+			"messageId": "m1",
+			"filename":  "fixture.txt",
+		}},
+	}
+
+	var buf bytes.Buffer
+	if err := WriteJSON(ctx, &buf, input); err != nil {
+		t.Fatalf("WriteJSON: %v", err)
+	}
+
+	var got []map[string]any
+	if err := json.Unmarshal(buf.Bytes(), &got); err != nil {
+		t.Fatalf("unmarshal: %v (out=%q)", err, buf.String())
+	}
+
+	if len(got) != 1 || got[0]["messageId"] != "m1" || got[0]["filename"] != "fixture.txt" {
+		t.Fatalf("attachment-specific result changed: %s", strings.TrimSpace(buf.String()))
+	}
+}
+
+func TestWriteJSON_ResultsOnlyListCommandStillReturnsItems(t *testing.T) {
+	ctx := WithJSONTransform(context.Background(), JSONTransform{ResultsOnly: true})
+	input := map[string]any{
+		"messages": []map[string]any{
+			{"id": "m1", "threadId": "t1"},
+			{"id": "m2", "threadId": "t2"},
+		},
+		"nextPageToken": "next-page",
+	}
+
+	var buf bytes.Buffer
+	if err := WriteJSON(ctx, &buf, input); err != nil {
+		t.Fatalf("WriteJSON: %v", err)
+	}
+
+	var got []map[string]any
+	if err := json.Unmarshal(buf.Bytes(), &got); err != nil {
+		t.Fatalf("unmarshal: %v (out=%q)", err, buf.String())
+	}
+
+	if len(got) != 2 || got[0]["id"] != "m1" || got[1]["id"] != "m2" {
+		t.Fatalf("list result changed: %s", strings.TrimSpace(buf.String()))
+	}
+}
+
 func TestWriteJSONTransformPreservesLargeNumbers(t *testing.T) {
 	ctx := WithJSONTransform(context.Background(), JSONTransform{Select: []string{"id"}})