Skip to content

Page the overdue report, and read every page of the account-wide lists - #1044

Open
thehale wants to merge 2 commits into
mainfrom
oncall-overdue-paging
Open

thehale wants to merge 2 commits into
mainfrom
oncall-overdue-paging

Conversation

@thehale

@thehale thehale commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

Written by @thehalebot

basecamp reports overdue reads 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 the next_page its get_overdue_todos already 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 N reads 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.
  • Summary: 15 of 214 overdue todos (…) when the report holds more than this page, from X-Total-Count. A report that fits on one page keeps 2 overdue todos (…).
  • Breadcrumb: next is basecamp reports overdue --page N+1 while Basecamp sends Link: rel="next", and is absent on the last page.
  • The output's data keeps its four lateness groups, holding this page's to-dos, plus the SDK's meta.
  • todos list --overdue, cards list --all-projects --overdue, assignments completed, timesheet report and reports assigned read every page and show the whole list, as before bc3#14537. The overdue listings keep their cap of 100, --all and --limit, and still refuse --page; they now say so when the SDK stops short of the last page.
  • The MCP server: get_overdue_todos takes page. Its dispatcher already wrapped any response with Link: 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 with scripts/sync-mcp-model.sh, which declares page and describes the paging. The catalog snapshot changes by that one description line. After the #1102 pin, the model marks the five lists paginated, so get_everything_overdue_todos, get_everything_overdue_cards, get_my_completed_assignments, get_timesheet_report and get_assigned_todos take page too, and the snapshot marks them paginated.

History

Invariants

  • The first page sends no page, and a page with more names the next one. TestReportsOverduePageWithMoreNamesTheNextPage serves two to-dos with Link: rel="next" and X-Total-Count: 21. The request has no query, the summary is 2 of 21 overdue todos (1 <1 week, 1 >1 month), and the next breadcrumb is basecamp reports overdue --page 2. On main, the summary was 2 overdue todos and there was no next.
  • --page reaches the wire, and a later page names the page after it. TestReportsOverdueLaterPageNamesThePageAfterIt runs --page 2 against a page with a next link: the request is page=2, the summary is 2 of 95 …, and next is --page 3.
  • A report on one page reads as before. TestReportsOverdueWholeReportOnOnePageNamesNoNextPage sends no paging headers: the summary is 2 overdue todos (…), and there is no next breadcrumb.
  • The MCP server follows the overdue report's pages. TestServerPagesTheOverdueReport calls get_overdue_todos, gets next_page: 2, and passes it back as page. Before the model sync, the second call failed with unknown parameter "page" for action "get_overdue_todos".
  • The surface snapshot gains only the new flag. .surface adds FLAG basecamp reports overdue --page type=int32.
  • The five lists read every page, in order. TestAccountWideListsReadEveryPage serves each route as two Link-paged pages. Each command requests the first page, then page=2, and shows both records in order. The test transport gains linked routes, which send Link: rel="next" the way Basecamp does.
  • The MCP server pages exactly the lists the SDK marks paginated. TestCatalogPaginatedActionsTakePage counts 68 Link-paginated operations, up from 63, each with one page parameter.
  • The Nix flake builds with each commit's go.sum. Each vendorHash is regenerated with make update-nix-hash, which built the flake with it.
  • bin/ci passes, and so does CI.

Builds on

Rejected Alternatives

  • Show the page number in the summary (page 4: 19 of 214). The absent next breadcrumb already marks the last page, and --page is what the caller just typed.
  • Read every page and merge them. That brings back the unbounded read bc3#14519 removed, from the client's side, and a merged report on a large account is too long to scan in a terminal anyway. notifications list pages the same way for the same reason.
  • Add --all beside --page. No one has asked for it, and the next breadcrumb already leads an agent through the pages.
  • Refuse --page 0 or a negative page, as comments list does. There the guard stops an explicit 0 from crawling every page. Here 0 means the first page and nothing crawls, so the command follows notifications list, which accepts it.

How to try it

Production Basecamp already pages the report. From this branch, make build, then ./bin/basecamp reports overdue on an account with more than 15 overdue to-dos: it says 15 of N overdue todos and offers --page 2. basecamp reports overdue from main says 15 overdue todos with no next page.

Further Work

  • --page on 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 with accountWideCollect, would save requests on a long list.

  • The TUI's assignments hub polls reports assigned every 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

@thehale
thehale requested a review from a team as a code owner November 18, 2026 21:27
Copilot AI balanced review requested due to automatic review settings November 18, 2026 21:27
@github-actions github-actions Bot added commands CLI command implementations sdk SDK wrapper and provenance tests Tests (unit and e2e) deps labels Nov 18, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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_todos accepts page.
  • 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 run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to 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

Comment thread go.mod Outdated
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

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@thehale
thehale force-pushed the oncall-overdue-paging branch from 730ea24 to 52625a6 Compare November 18, 2026 21:31
Copilot AI balanced review requested due to automatic review settings November 18, 2026 21:31
Copilot AI previously approved these changes Nov 18, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approved

No active review issues are recorded for the overdue-report pagination update.

1 open issue

Review effort: Balanced

@thehale
thehale force-pushed the oncall-overdue-paging branch from 52625a6 to 9b6ac16 Compare November 18, 2026 21:35
Copilot AI balanced review requested due to automatic review settings November 18, 2026 21:35
Copilot AI dismissed their stale review, a newer Copilot review was requested November 18, 2026 21:35
Copilot AI previously approved these changes Nov 18, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approved

No active review issues were identified for the CLI and MCP overdue-report pagination changes.

1 open issue

Review effort: Balanced

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
@thehale
thehale force-pushed the oncall-overdue-paging branch from 9b6ac16 to a2bb5b6 Compare November 20, 2026 01:24
Copilot AI balanced review requested due to automatic review settings November 20, 2026 01:24
Copilot AI dismissed their stale review, a newer Copilot review was requested November 20, 2026 01:24
@github-actions github-actions Bot added the docs label Nov 20, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unsorted overdue todo and card listings fetch every page despite a local limit, causing unnecessary requests and allowing failures on unneeded pages to prevent output.

2 open issues

Review effort: Balanced

}

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
@thehale
thehale force-pushed the oncall-overdue-paging branch from a2bb5b6 to 452d856 Compare November 20, 2026 01:33
@thehale thehale changed the title Page the overdue to-dos report in the CLI and its MCP server Page the overdue report, and read every page of the account-wide lists Nov 20, 2026
Copilot AI balanced review requested due to automatic review settings November 20, 2026 01:33

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

A maintainer must confirm prerequisite merges and deployment order because basecamp-sdk#1102 remains open and bc3#14537 was unavailable for review.

2 open issues

Review effort: Balanced

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

commands CLI command implementations deps docs sdk SDK wrapper and provenance tests Tests (unit and e2e)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants