Repository navigation
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
The SDK bump leaves the Nix vendorHash unchanged, causing fresh Nix builds to fail with a dependency hash mismatch.
1 open issue
What changed in this PR
Adds explicit paging to the overdue to-dos report in the CLI and its MCP server, so users can reach results beyond the first page without fetching the entire report.
Changes:
- Adds
--page, report-wide totals in summaries, and next-page breadcrumbs. - Updates the SDK pin and MCP model so
get_overdue_todosacceptspage. - Adds CLI and MCP pagination regression tests.
[!TIP]
If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or rungh pr ready --undo.
Click "Ready for review" or rungh pr readyto reengage.
| File | Description |
|---|---|
internal/version/sdk-provenance.json |
Records the updated SDK pin. |
internal/mcpserver/testdata/catalog_snapshot.txt |
Describes the report as a single-page response. |
internal/mcpserver/server_test.go |
Tests passing next_page back through MCP. |
internal/mcpserver/model/PROVENANCE.json |
Records the synced model revision. |
internal/mcpserver/model/openapi.json |
Declares page and documents report pagination. |
internal/commands/reports.go |
Adds page selection, total counts, and navigation. |
internal/commands/reports_test.go |
Covers first, later, and single-page reports. |
go.sum |
Updates SDK checksums. |
go.mod |
Pins the SDK revision supporting report paging. |
.surface |
Records the new --page flag. |
Review effort: Balanced
| charm.land/bubbletea/v2 v2.1.0 | ||
| charm.land/lipgloss/v2 v2.0.6 | ||
| github.com/basecamp/basecamp-sdk/go v0.36.0 | ||
| github.com/basecamp/basecamp-sdk/go v0.36.1-0.20261117211228-8f70192fb5a7 |
There was a problem hiding this comment.
Written by @thehalebot
Fixed. The commit updates nix/package.nix to the hash the Nix flake build reported for the new go.sum, as #1034 did with its SDK bump. The Nix flake builds check reruns on 9b6ac16.
730ea24 to
52625a6
Compare
52625a6 to
9b6ac16
Compare
Basecamp answers the overdue to-dos report one page at a time since basecamp/bc3#14519. The reports overdue command showed the first page as if it were the whole report and counted only that page. It reads one page, says how many to-dos the whole report holds, and offers the next page while one remains. The MCP server's get_overdue_todos already answered next_page, but refused it as an unknown parameter. The SDK model it reads declares page, so the next page can be asked for. Bumps basecamp-sdk to v0.37.0, which takes a page on the overdue report (basecamp/basecamp-sdk#1100). The new go.sum changes the Nix vendorHash, so nix/package.nix carries the refreshed hash. https://app.basecamp.com/2914079/buckets/27/card_tables/cards/10512247737 https://app.basecamp.com/2914079/buckets/27/card_tables/cards/10516396199
9b6ac16 to
a2bb5b6
Compare
| } | ||
|
|
||
| todos, err := app.Account().Everything().OverdueTodos(cmd.Context(), taskFilters) | ||
| result, err := app.Account().Everything().OverdueTodos(cmd.Context(), 0, taskFilters) |
Basecamp answers the overdue to-dos and cards, completed assignments, the timesheet report and the assigned to-dos report 50 records a page (basecamp/bc3#14537), where each used to come whole. Once that ships, basecamp-sdk v0.37.0 would hand those commands the first page as if it were the whole list. They now read every page, so a list longer than 50 is still complete. Pins basecamp-sdk to basecamp/basecamp-sdk#1102, which follows these pages, until a release carries it, and re-syncs the MCP server's model from it, so its five matching actions take a page. The new go.sum changes the Nix vendorHash. https://app.basecamp.com/2914079/buckets/27/card_tables/cards/10516396199
a2bb5b6 to
452d856
Compare


Written by @thehalebot
basecamp reports overduereads the overdue to-dos report once. Since basecamp/bc3#14519, Basecamp answers that report one page at a time: 15, 30, 50, then 100 to-dos, most recently due first, each page holding the same four lateness groups. So in production the command shows the first page as if it were the whole report, and its summary counts only that page. This change gives the command--page, has the summary say how many to-dos the whole report holds, and offers the next page as a breadcrumb while one remains. It also lets the CLI's MCP server (basecamp mcp) take thenext_pageitsget_overdue_todosalready answers, which it refuses in production as an unknown parameter.The second commit is for basecamp/bc3#14537, which pages five more account-wide lists at 50 a page: overdue to-dos, overdue cards, completed assignments, the timesheet report and the assigned to-dos report, each answered whole until now. On basecamp-sdk v0.37.0 those commands would show the first page as the whole list once it ships. They now read every page, through basecamp/basecamp-sdk#1102.
Merge order: merge after basecamp/bc3#14537 and after basecamp/basecamp-sdk#1102, whose head this pins.
What changes for users
--page Nreads page N of the report. Without it, the command reads the first page, as before. The help says the longest-overdue to-dos are on the last pages.15 of 214 overdue todos (…)when the report holds more than this page, fromX-Total-Count. A report that fits on one page keeps2 overdue todos (…).nextisbasecamp reports overdue --page N+1while Basecamp sendsLink: rel="next", and is absent on the last page.meta.todos list --overdue,cards list --all-projects --overdue,assignments completed,timesheet reportandreports assignedread every page and show the whole list, as before bc3#14537. The overdue listings keep their cap of 100,--alland--limit, and still refuse--page; they now say so when the SDK stops short of the last page.get_overdue_todostakespage. Its dispatcher already wrapped any response withLink: rel="next"as{"next_page": N, "results": ...}, but it rejects parameters an operation doesn't declare. The vendored SDK model (internal/mcpserver/model/) is re-synced from 8f70192 withscripts/sync-mcp-model.sh, which declarespageand describes the paging. The catalog snapshot changes by that one description line. After the #1102 pin, the model marks the five lists paginated, soget_everything_overdue_todos,get_everything_overdue_cards,get_my_completed_assignments,get_timesheet_reportandget_assigned_todostakepagetoo, and the snapshot marks thempaginated.History
Reports().OverdueTodoscall since, which was the whole report until bc3#14519 paged the endpoint. That change stopped a single request growing a Puma worker to several GB.OverdueTodos(ctx, page)reads exactly one page, following basecamp-sdk#617, and reports an unfollowedrel="next"asMeta.TruncatedandX-Total-CountasMeta.TotalCount. It carries no pagination trait, because the report is an object of four arrays and the trait names one, the same carve-out asGetMyNotifications. So no SDK walks the report.notifications list, the CLI's other object-of-several-lists read on that carve-out:--pagewith anInt32Vardefaulting to the first page, and anextbreadcrumb (Notifications say 100+ unread when the server's cap is reached #799). Bound the account-wide listings, and drop the boost aggregate #590 set the rule that a listing needs an escape hatch past its first read, which--pagegives here.TestCatalogModelProvenanceholds to the SDK commitgo.modpins, so the model sync rides with the pin. MCP follow-up: converge the Codex review of #662 #663 synthesizedpagefor operations the model marks paginated without declaring it. The overdue report isn't marked paginated (no trait, as above), so it needed the parameter declared in the SDK, which #1100 did.vendorHashthat anygo.sumchange invalidates. Let assignments notify people with --notify #1034's SDK bump refreshed it in the same change, and so does this one.API-COVERAGE.mdandACCOUNT-WIDE-LISTINGS.mdcallreports overduea lateness-bucketed report, distinct fromtodos list --all-projects --overdue. That stays true, so they are unchanged.Invariants
page, and a page with more names the next one.TestReportsOverduePageWithMoreNamesTheNextPageserves two to-dos withLink: rel="next"andX-Total-Count: 21. The request has no query, the summary is2 of 21 overdue todos (1 <1 week, 1 >1 month), and thenextbreadcrumb isbasecamp reports overdue --page 2. Onmain, the summary was2 overdue todosand there was nonext.--pagereaches the wire, and a later page names the page after it.TestReportsOverdueLaterPageNamesThePageAfterItruns--page 2against a page with a next link: the request ispage=2, the summary is2 of 95 …, andnextis--page 3.TestReportsOverdueWholeReportOnOnePageNamesNoNextPagesends no paging headers: the summary is2 overdue todos (…), and there is nonextbreadcrumb.TestServerPagesTheOverdueReportcallsget_overdue_todos, getsnext_page: 2, and passes it back aspage. Before the model sync, the second call failed withunknown parameter "page" for action "get_overdue_todos"..surfaceaddsFLAG basecamp reports overdue --page type=int32.TestAccountWideListsReadEveryPageserves each route as two Link-paged pages. Each command requests the first page, thenpage=2, and shows both records in order. The test transport gainslinkedroutes, which sendLink: rel="next"the way Basecamp does.TestCatalogPaginatedActionsTakePagecounts 68 Link-paginated operations, up from 63, each with onepageparameter.go.sum. EachvendorHashis regenerated withmake update-nix-hash, which built the flake with it.bin/cipasses, and so does CI.Builds on
1d0f5e04asv0.37.1-0.20261120012501-1d0f5e04225d, withmake bump-sdk, the way Show who completed a to-do or card, and when, by bumping basecamp-sdk to 63115e79 #942 pinned an SDK commit. Bumping to the release that carries it needs no code change here.Rejected Alternatives
page 4: 19 of 214). The absentnextbreadcrumb already marks the last page, and--pageis what the caller just typed.notifications listpages the same way for the same reason.--allbeside--page. No one has asked for it, and thenextbreadcrumb already leads an agent through the pages.--page 0or a negative page, ascomments listdoes. There the guard stops an explicit 0 from crawling every page. Here 0 means the first page and nothing crawls, so the command followsnotifications list, which accepts it.How to try it
Production Basecamp already pages the report. From this branch,
make build, then./bin/basecamp reports overdueon an account with more than 15 overdue to-dos: it says15 of N overdue todosand offers--page 2.basecamp reports overduefrommainsays15 overdue todoswith no next page.Further Work
--pageon the two overdue listings. They read every page and trim to the cap locally, as when the endpoints were unpaged. Walking only until the cap, as the other account-wide listings do withaccountWideCollect, would save requests on a long list.The TUI's assignments hub polls
reports assignedevery minute per account, and now reads every page of it each time.The SDK's description of the operation says "latest first", which the vendored MCP model and catalog snapshot carry. It means most recently due first; the wording belongs in basecamp-sdk and comes here with the next model sync.
Card: https://app.basecamp.com/2914079/buckets/27/card_tables/cards/10512247737