Comment flags on all show commands + bug fixes (#394)

* Fix renderer comments suppression causing data loss

renderObject unconditionally skipped the "comments" key, then
topLevelComments tried to reconstruct it as []map[string]any.
When comments was a different shape (string, int, []string) —
as happens with `basecamp api get` — reconstruction returned nil
and data was silently dropped.

Only skip "comments" in the field loop when topLevelComments
returns non-nil. Both styled and markdown renderers.

* Fix false-positive attachment regression tests

TestStyledRenderObjectPreservesUnknownAttachmentFields asserted
custom_attachments_report survived — but that key doesn't end
with _attachments, so it passed under the old code too.
previewable_attachments was in the test data but never asserted.

Assert previewable_attachments values appear in output (both
styled and markdown). Remove the misleading assertion.

* Redesign commentFlags for three-flag model

Three mutually exclusive flags: --comments / --no-comments /
--all-comments. addCommentFlags(cmd, defaultOn) controls whether
comments are fetched by default (show) or require opt-in (typed
show commands).

New fetchCommentsForRecording derives count from API response
metadata, not the parent's comments_count. fetchRecordingComments
becomes a thin wrapper that falls back to the parent's count when
Meta.TotalCount is unavailable.

* Always fetch comments in show; gate non-commentable types

Drop the comments_count gate — basecamp show now always attempts
comment fetching for commentable types. Skip the fetch for people
and boosts which don't support comments.

Update tests: expect the extra comments request, add
X-Total-Count header support to mock transport, rename
TestShowCommentsMissingField to TestShowSkipsCommentsForNonCommentableTypes.

* Add --comments / --no-comments / --all-comments to typed show commands

Wire fetchCommentsForRecording into all commentable show commands:
todos, messages, cards, files, todolists, schedule (both paths),
checkins (question + answer), forwards, chat line.

defaultOn=false means typed commands require --comments or
--all-comments to opt in. Attachment notices are merged via
applyNotices. Comments on comments are excluded (flat model).

* Update .surface and SKILL.md for comment flags

Regenerate CLI surface snapshot with new --comments,
--no-comments, --all-comments flags on typed show commands.
Acknowledge comments show flag removal in .surface-breaking.
Update skill with typed show command examples.

* Fix empty comments array leaking as field; rename tests

Use isCommentsArray to decide whether to suppress the raw
comments field, not len(comments) > 0. topLevelComments returns
nil for empty arrays (toMapSlice on []any{}), so empty comments
arrays were rendered as regular fields instead of being suppressed.

Rename attachment tests to reflect updated fixture focus.

* Exclude comment type from automatic comment fetch

Add comment/comments CLI aliases and Comment API type to
isCommentableShowType's non-commentable list. Comments are flat —
attempting to fetch comments-on-comments wastes a request and can
produce misleading diagnostics.

* Wire comment flags into checkins parent shortcut commands

Register --comments/--no-comments/--all-comments on the parent
question and answer commands so both entry points (shortcut and
explicit show) accept the same flags.

* Regenerate .surface; remove stale .surface-breaking entries

Fresh surface snapshot reflects comment type exclusion and
checkins parent flag wiring. Remove the comments show flag
removal entries from .surface-breaking — the flags were never
in the regenerated baseline.

* Extract commentEnrichment.apply helper; collapse enrichment tail

Every typed show command repeated the same withComments / applyNotices /
breadcrumbs sequence. The new apply() method on commentEnrichment returns
enriched data and composed opts in one call. All 11 call sites now use it.

Includes tests for apply() (nil, populated, breadcrumb composition) and
isCommentableShowType (CLI aliases, generic lookups, API types).

* Render comments after entity presenter in styled and markdown output

The schema-driven presenter only renders fields declared in YAML schemas,
so comments injected via withComments were silently dropped in styled and
markdown output. Extract comments from NormalizeData(resp.Data) — never
from DisplayData — and append a comments section after the presenter body.

Includes tests for entity+comments rendering (plain entity and DisplayData
split path, both formats) and isCommentsArray coverage.

* Address review feedback: rename test, add truncation notice fallback

Rename TestShowNoCommentsWhenCountZero to TestShowFetchesCommentsEvenWhenCountZero
to match the actual assertion (comments ARE fetched even with count 0).

When Meta.TotalCount is missing from the API response but the parent's
comments_count indicates truncation occurred, recompute the truncation
notice so the user sees a warning and the --all-comments breadcrumb.

Author: jeremy

.surface

@@ -761,3 +761,4 @@ FLAG basecamp chat messages --campfire type=string
 FLAG basecamp chat post --campfire type=string
 FLAG basecamp chat show --campfire type=string
 FLAG basecamp chat upload --campfire type=string
+

.surface-breaking

@@ -267,6 +267,7 @@ You can pass either a card ID or a Basecamp URL:
 	}
 
 	dlDir := addDownloadAttachmentsFlag(cmd)
+	cf := addCommentFlags(cmd, false)
 
 	cmd.RunE = func(cmd *cobra.Command, args []string) error {
 		app := appctx.FromContext(cmd.Context())
@@ -288,6 +289,8 @@ You can pass either a card ID or a Basecamp URL:
 			return convertSDKError(err)
 		}
 
+		enrichment := fetchCommentsForRecording(cmd.Context(), app, cardIDStr, cf)
+
 		opts := []output.ResponseOption{
 			output.WithSummary(fmt.Sprintf("Card #%s: %s", cardIDStr, card.Title)),
 			output.WithBreadcrumbs(
@@ -300,6 +303,7 @@ You can pass either a card ID or a Basecamp URL:
 		}
 
 		data := any(card)
+		attachmentNotice := ""
 		contentAtts := downloadableAttachments(richtext.ParseAttachments(card.Content))
 		descAtts := downloadableAttachments(richtext.ParseAttachments(card.Description))
 		total := len(contentAtts) + len(descAtts)
@@ -317,17 +321,19 @@ You can pass either a card ID or a Basecamp URL:
 			if len(descAtts) > 0 {
 				data = withAttachmentMeta(data, "description", descAtts, descDL)
 			}
-			notice := fmt.Sprintf("%d attachment(s) — download: basecamp attachments download %s",
+			attachmentNotice = fmt.Sprintf("%d attachment(s) — download: basecamp attachments download %s",
 				total, cardIDStr)
 			if dl != nil && dl.Notice != "" {
-				notice += "; " + dl.Notice
+				attachmentNotice += "; " + dl.Notice
 			}
 			opts = append(opts,
-				output.WithNotice(notice),
 				output.WithBreadcrumbs(attachmentBreadcrumb(cardIDStr, total)),
 			)
 		}
 
+		data, extraOpts := enrichment.apply(data, attachmentNotice)
+		opts = append(opts, extraOpts...)
+
 		return app.OK(data, opts...)
 	}
 

internal/commands/cards.go

@@ -627,6 +627,8 @@ func runChatUpload(cmd *cobra.Command, app *appctx.App, chatID, project, filePat
 }
 
 func newChatLineShowCmd(project, chatID *string) *cobra.Command {
+	var cf *commentFlags
+
 	cmd := &cobra.Command{
 		Use:     "line <id|url>",
 		Aliases: []string{"show"},
@@ -697,9 +699,13 @@ You can pass either a line ID or a Basecamp line URL:
 			if line.Creator != nil {
 				creatorName = line.Creator.Name
 			}
+
+			enrichment := fetchCommentsForRecording(cmd.Context(), app, lineID, cf)
+			data, commentOpts := enrichment.apply(line, "")
 			summary := fmt.Sprintf("Line #%s by %s", lineID, creatorName)
 
-			return app.OK(line,
+			opts := make([]output.ResponseOption, 0, 4+len(commentOpts))
+			opts = append(opts,
 				output.WithSummary(summary),
 				output.WithEntity("chat_line"),
 				output.WithDisplayData(chatLineDisplayData(line)),
@@ -716,8 +722,14 @@ You can pass either a line ID or a Basecamp line URL:
 					},
 				),
 			)
+			opts = append(opts, commentOpts...)
+
+			return app.OK(data, opts...)
 		},
 	}
+
+	cf = addCommentFlags(cmd, false)
+
 	return cmd
 }
 

internal/commands/chat.go

@@ -153,13 +153,16 @@ func newCheckinsQuestionCmd(project *string) *cobra.Command {
 		Use:   "question <id|url>",
 		Short: "Show or manage a question",
 		Args:  cobra.MaximumNArgs(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			// Show help when invoked with no arguments
-			if len(args) == 0 {
-				return missingArg(cmd, "<id|url>")
-			}
-			return runCheckinsQuestionShow(cmd, *project, args[0])
-		},
+	}
+
+	cf := addCommentFlags(cmd, false)
+
+	cmd.RunE = func(cmd *cobra.Command, args []string) error {
+		// Show help when invoked with no arguments
+		if len(args) == 0 {
+			return missingArg(cmd, "<id|url>")
+		}
+		return runCheckinsQuestionShow(cmd, *project, args[0], cf)
 	}
 
 	cmd.AddCommand(
@@ -172,7 +175,7 @@ func newCheckinsQuestionCmd(project *string) *cobra.Command {
 }
 
 func newCheckinsQuestionShowCmd(project *string) *cobra.Command {
-	return &cobra.Command{
+	cmd := &cobra.Command{
 		Use:   "show <id|url>",
 		Short: "Show question details",
 		Long: `Display details of a check-in question.
@@ -181,13 +184,18 @@ You can pass either a question ID or a Basecamp URL:
   basecamp checkins question show 789 --in my-project
   basecamp checkins question show https://3.basecamp.com/123/buckets/456/questionnaires/questions/789`,
 		Args: cobra.ExactArgs(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			return runCheckinsQuestionShow(cmd, *project, args[0])
-		},
 	}
+
+	cf := addCommentFlags(cmd, false)
+
+	cmd.RunE = func(cmd *cobra.Command, args []string) error {
+		return runCheckinsQuestionShow(cmd, *project, args[0], cf)
+	}
+
+	return cmd
 }
 
-func runCheckinsQuestionShow(cmd *cobra.Command, project, questionIDStr string) error {
+func runCheckinsQuestionShow(cmd *cobra.Command, project, questionIDStr string, cf *commentFlags) error {
 	app := appctx.FromContext(cmd.Context())
 
 	if err := ensureAccount(cmd, app); err != nil {
@@ -230,9 +238,12 @@ func runCheckinsQuestionShow(cmd *cobra.Command, project, questionIDStr string)
 		return convertSDKError(err)
 	}
 
+	enrichment := fetchCommentsForRecording(cmd.Context(), app, questionIDStr, cf)
+	data, commentOpts := enrichment.apply(question, "")
 	summary := fmt.Sprintf("%s (%d answers)", question.Title, question.AnswersCount)
 
-	return app.OK(question,
+	opts := make([]output.ResponseOption, 0, 2+len(commentOpts))
+	opts = append(opts,
 		output.WithSummary(summary),
 		output.WithBreadcrumbs(
 			output.Breadcrumb{
@@ -247,6 +258,9 @@ func runCheckinsQuestionShow(cmd *cobra.Command, project, questionIDStr string)
 			},
 		),
 	)
+	opts = append(opts, commentOpts...)
+
+	return app.OK(data, opts...)
 }
 
 func newCheckinsQuestionCreateCmd(project *string) *cobra.Command {
@@ -620,13 +634,16 @@ func newCheckinsAnswerCmd(project *string) *cobra.Command {
 		Use:   "answer <id|url>",
 		Short: "Show or manage an answer",
 		Args:  cobra.MaximumNArgs(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			// Show help when invoked with no arguments
-			if len(args) == 0 {
-				return missingArg(cmd, "<id|url>")
-			}
-			return runCheckinsAnswerShow(cmd, *project, args[0])
-		},
+	}
+
+	cf := addCommentFlags(cmd, false)
+
+	cmd.RunE = func(cmd *cobra.Command, args []string) error {
+		// Show help when invoked with no arguments
+		if len(args) == 0 {
+			return missingArg(cmd, "<id|url>")
+		}
+		return runCheckinsAnswerShow(cmd, *project, args[0], cf)
 	}
 
 	cmd.AddCommand(
@@ -639,7 +656,7 @@ func newCheckinsAnswerCmd(project *string) *cobra.Command {
 }
 
 func newCheckinsAnswerShowCmd(project *string) *cobra.Command {
-	return &cobra.Command{
+	cmd := &cobra.Command{
 		Use:   "show <id|url>",
 		Short: "Show answer details",
 		Long: `Display details of a check-in answer.
@@ -648,13 +665,18 @@ You can pass either an answer ID or a Basecamp URL:
   basecamp checkins answer show 789 --in my-project
   basecamp checkins answer show https://3.basecamp.com/123/buckets/456/question_answers/789`,
 		Args: cobra.ExactArgs(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			return runCheckinsAnswerShow(cmd, *project, args[0])
-		},
 	}
+
+	cf := addCommentFlags(cmd, false)
+
+	cmd.RunE = func(cmd *cobra.Command, args []string) error {
+		return runCheckinsAnswerShow(cmd, *project, args[0], cf)
+	}
+
+	return cmd
 }
 
-func runCheckinsAnswerShow(cmd *cobra.Command, project, answerIDStr string) error {
+func runCheckinsAnswerShow(cmd *cobra.Command, project, answerIDStr string, cf *commentFlags) error {
 	app := appctx.FromContext(cmd.Context())
 
 	if err := ensureAccount(cmd, app); err != nil {
@@ -705,14 +727,18 @@ func runCheckinsAnswerShow(cmd *cobra.Command, project, answerIDStr string) erro
 	if len(date) > 10 {
 		date = date[:10]
 	}
+
+	enrichment := fetchCommentsForRecording(cmd.Context(), app, answerIDStr, cf)
+	data, commentOpts := enrichment.apply(answer, "")
 	summary := fmt.Sprintf("Answer by %s on %s", author, date)
 
 	questionID := ""
 	if answer.Parent != nil {
 		questionID = strconv.FormatInt(answer.Parent.ID, 10)
 	}
 
-	return app.OK(answer,
+	opts := make([]output.ResponseOption, 0, 2+len(commentOpts))
+	opts = append(opts,
 		output.WithSummary(summary),
 		output.WithBreadcrumbs(
 			output.Breadcrumb{
@@ -727,6 +753,9 @@ func runCheckinsAnswerShow(cmd *cobra.Command, project, answerIDStr string) erro
 			},
 		),
 	)
+	opts = append(opts, commentOpts...)
+
+	return app.OK(data, opts...)
 }
 
 func newCheckinsAnswerCreateCmd(project *string) *cobra.Command {