Say a whole-board cards list was capped in every output mode (#933)

The 100-per-column cap on a whole-board `cards list` reported itself only
through an informational notice, which --agent and --quiet drop, so an agent
script got a short list in silence. Make the notice a diagnostic (stderr in
quiet modes, stdout untouched) and name each cut column in
meta.truncated_columns with what was shown and the total.

Author: jeremy

internal/commands/cards.go

@@ -97,8 +97,10 @@ func newCardsListCmd(project, cardTable *string) *cobra.Command {
 		Use:   "list",
 		Short: "List cards",
 		Long: "List the cards in a project's card table, or across every project with --all-projects.\n\n" +
-			"Without --column the listing covers every column, up to 100 cards from each; --all lifts\n" +
-			"that cap. --column lists one column in full unless --limit or --page narrows it.\n\n" +
+			"Without --column the listing covers every column but stops at 100 cards from each, leaving\n" +
+			"the rest out; --all lifts that cap. A capped listing says so in every output mode: a notice\n" +
+			"(on stderr with --agent or --quiet) and meta.truncated_columns in the JSON envelope.\n" +
+			"--column lists one column in full unless --limit or --page narrows it.\n\n" +
 			"With --all-projects the listing comes from the account-wide card aggregates, grouped by\n" +
 			"project. --status completed, --unassigned, --no-due-date, --not-now, and --overdue each\n" +
 			"select a different aggregate and are account-wide only.\n\n" +
@@ -626,6 +628,7 @@ func runCardsListInProject(cmd *cobra.Command, app *appctx.App, opts cardsListOp
 			perColumn = nil
 		}
 		var truncated []string
+		var truncatedColumns []map[string]any
 		for _, col := range cardTableData.Lists {
 			cardsResult, err := app.Account().Cards().List(cmd.Context(), col.ID, perColumn)
 			if err != nil {
@@ -634,17 +637,24 @@ func runCardsListInProject(cmd *cobra.Command, app *appctx.App, opts cardsListOp
 			allCards = append(allCards, cardsResult.Cards...)
 			if cardsResult.Meta.Truncated {
 				truncated = append(truncated, truncatedColumnLabel(col, cardsResult.Meta.TotalCount))
+				truncatedColumns = append(truncatedColumns, truncatedColumnMeta(col, len(cardsResult.Cards), cardsResult.Meta.TotalCount))
 			}
 		}
 
 		if opts.sortField != "" {
 			sortCards(allCards, opts.sortField, opts.reverse)
 		}
 
+		// The cap drops cards the caller didn't ask to drop, so it is a
+		// diagnostic, not an informational notice: --agent and --quiet print
+		// data alone and would otherwise hand back a short list in silence.
 		if len(truncated) > 0 {
-			respOpts = append(respOpts, output.WithNotice(fmt.Sprintf(
-				"Showing the first %d cards of %s; use --column <id> --all for every card in one column, or --all for every column",
-				cardsPerColumnLimit, strings.Join(truncated, ", "))))
+			respOpts = append(respOpts,
+				output.WithDiagnostic(fmt.Sprintf(
+					"Showing the first %d cards of %s; use --column <id> --all for every card in one column, or --all for every column",
+					cardsPerColumnLimit, strings.Join(truncated, ", "))),
+				output.WithMeta("truncated_columns", truncatedColumns),
+			)
 		}
 	}
 
@@ -673,6 +683,16 @@ func truncatedColumnLabel(col basecamp.CardColumn, total int) string {
 	return col.Title
 }
 
+// truncatedColumnMeta describes a column the aggregate listing cut short for
+// meta.truncated_columns; total is omitted when the API didn't report one.
+func truncatedColumnMeta(col basecamp.CardColumn, shown, total int) map[string]any {
+	m := map[string]any{"id": col.ID, "title": col.Title, "shown": shown}
+	if total > 0 {
+		m["total"] = total
+	}
+	return m
+}
+
 // countAccountWideCards totals the cards inside the project groups.
 func countAccountWideCards(groups []basecamp.BucketCardsGroup) int {
 	total := 0

internal/commands/cards_list_columns_test.go

@@ -87,16 +87,22 @@ func cardsJSON(firstID, count int) string {
 }
 
 func runCardTableList(t *testing.T, format output.Format, args ...string) (*cardTableTransport, *bytes.Buffer, error) {
+	t.Helper()
+	transport, buf, _, err := runCardTableListStderr(t, format, args...)
+	return transport, buf, err
+}
+
+func runCardTableListStderr(t *testing.T, format output.Format, args ...string) (*cardTableTransport, *bytes.Buffer, *bytes.Buffer, error) {
 	t.Helper()
 	transport := &cardTableTransport{}
 	app, _ := newTestAppWithTransport(t, transport)
-	buf := &bytes.Buffer{}
-	app.Output = output.New(output.Options{Format: format, Writer: buf, ErrWriter: &bytes.Buffer{}})
+	buf, errBuf := &bytes.Buffer{}, &bytes.Buffer{}
+	app.Output = output.New(output.Options{Format: format, Writer: buf, ErrWriter: errBuf})
 	if format == output.FormatCount {
 		app.Flags.Count = true
 	}
 	err := executeCommand(NewCardsCmd(), app, append([]string{"list", "--in", "123", "--card-table", "777"}, args...)...)
-	return transport, buf, err
+	return transport, buf, errBuf, err
 }
 
 // TestCardsListAcrossColumnsCapsEachColumn pins that listing a whole card table
@@ -119,6 +125,53 @@ func TestCardsListAcrossColumnsCapsEachColumn(t *testing.T) {
 	assert.Contains(t, resp.Notice, "--all")
 }
 
+// TestCardsListAcrossColumnsCapIsMachineReadable pins that the JSON envelope
+// names every column the cap cut short, with what it showed and the total, so
+// a script can tell a capped listing from a complete one without parsing prose.
+func TestCardsListAcrossColumnsCapIsMachineReadable(t *testing.T) {
+	_, buf, err := runCardTableList(t, output.FormatJSON)
+	require.NoError(t, err)
+
+	var resp struct {
+		Meta struct {
+			TruncatedColumns []map[string]any `json:"truncated_columns"`
+		} `json:"meta"`
+	}
+	require.NoError(t, json.Unmarshal(buf.Bytes(), &resp))
+	require.Len(t, resp.Meta.TruncatedColumns, 1, "only Done is cut short")
+	done := resp.Meta.TruncatedColumns[0]
+	assert.EqualValues(t, 2, done["id"])
+	assert.Equal(t, "Done", done["title"])
+	assert.EqualValues(t, cardsPerColumnLimit, done["shown"])
+	assert.EqualValues(t, doneColumnCards, done["total"])
+}
+
+// TestCardsListAcrossColumnsCapIsLoudInQuietModes pins that --agent and --quiet,
+// which print the data alone, still say on stderr that the list was cut short,
+// while stdout stays the bare card array.
+func TestCardsListAcrossColumnsCapIsLoudInQuietModes(t *testing.T) {
+	_, buf, errBuf, err := runCardTableListStderr(t, output.FormatQuiet)
+	require.NoError(t, err)
+
+	assert.Contains(t, errBuf.String(), "notice: Showing the first 100 cards of Done (140 total)")
+
+	var data []map[string]any
+	require.NoError(t, json.Unmarshal(buf.Bytes(), &data), "stdout must stay data-only")
+	assert.Len(t, data, 3+cardsPerColumnLimit)
+}
+
+// TestCardsListAcrossColumnsUncappedIsQuiet pins that a listing nothing cut
+// short carries no notice and no truncated_columns, in either channel.
+func TestCardsListAcrossColumnsUncappedIsQuiet(t *testing.T) {
+	_, _, errBuf, err := runCardTableListStderr(t, output.FormatQuiet, "--all")
+	require.NoError(t, err)
+	assert.Empty(t, errBuf.String())
+
+	_, buf, err := runCardTableList(t, output.FormatJSON, "--all")
+	require.NoError(t, err)
+	assert.NotContains(t, buf.String(), "truncated_columns")
+}
+
 // TestCardsListAcrossColumnsAllWalksEveryPage pins that --all, now accepted
 // without --column, restores the full walk of every column.
 func TestCardsListAcrossColumnsAllWalksEveryPage(t *testing.T) {