Account-wide entitlement usage visibility and usage_get capability - #1240
Merged
Merged
Conversation
…lity Extend the account usage page with all entitlement resources grouped by daily rates, counts, storage, and per-item limits. Each row shows current use, plan limit, percent, a progress bar, near-limit warnings (>80%), and plain-language guidance on what counts and how to reduce usage. Add shared entitlement usage snapshot logic, resource visibility copy, and the read-only account usage_get MCP capability for agent parity. Cross-link billing plan cards and usage warnings to /account/billing. Co-authored-by: Kent C. Dodds <me+github@kentcdodds.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (2)
📝 WalkthroughWalkthroughThe change centralizes entitlement usage calculation in snapshots, adds resource visibility metadata, updates account usage presentation with grouped progress panels and warnings, links billing plans to usage, and exposes the same data through the authenticated ChangesEntitlement usage reporting
Estimated code review effort: 4 (Complex) | ~45 minutes Sequence Diagram(s)sequenceDiagram
participant AccountUser
participant AccountUsagePage
participant accountUsageData
participant readEntitlementUsageSnapshot
participant UsageSources
AccountUser->>AccountUsagePage: open account usage
AccountUsagePage->>accountUsageData: load usage data
accountUsageData->>readEntitlementUsageSnapshot: request snapshot
readEntitlementUsageSnapshot->>UsageSources: collect usage and limits
UsageSources-->>readEntitlementUsageSnapshot: resource rows and warnings
readEntitlementUsageSnapshot-->>accountUsageData: plan, day, rows, warnings
accountUsageData-->>AccountUsagePage: grouped usage data
AccountUsagePage-->>AccountUser: render progress, guidance, and billing links
Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
kody-bot
marked this pull request as ready for review
August 5, 2026 16:48
Co-authored-by: Kent C. Dodds <me+github@kentcdodds.com>
Contributor
|
🔎 Preview deployed: https://kody-pr-1240.kody-a99.workers.dev Worker: Mocks:
|
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 9afb610. Configure here.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (4)
packages/worker/src/entitlements/resource-visibility.ts (1)
142-159: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winConsider enforcing completeness of the ordered resource list.
satisfies ReadonlyArray<EntitlementResource>only proves each entry is a valid resource. It does not prove that every registered resource appears. If a new resource is added toEntitlementResource,entitlementResourceVisibilityfails to compile, but this list silently omits the resource, and the account page andusage_getthen hide it.♻️ Proposed compile-time completeness check
] as const satisfies ReadonlyArray<EntitlementResource> + +// Fails to compile when a resource is missing from the ordered list above. +type MissingUsageResource = Exclude< + EntitlementResource, + (typeof accountUsageEntitlementResources)[number] +> +const _allResourcesListed: MissingUsageResource extends never ? true : never = + true +void _allResourcesListed🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/worker/src/entitlements/resource-visibility.ts` around lines 142 - 159, Update accountUsageEntitlementResources to enforce compile-time completeness against the full EntitlementResource union, not only validate individual entries. Add a type-level check that fails when any registered resource is omitted while preserving the existing ordered list and EntitlementResource entry validation.packages/worker/src/entitlements/usage-snapshot.node.test.ts (1)
104-117: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd assertions for non-counter resource kinds.
Both tests exercise counters only. Add a case that asserts
percentOfLimitisnullandoverEightyPercentisfalseforemail_message_bytes(per_unit_max) and forpersistent_package_services(boolean_allowance). That case pins the behavior discussed inpackages/worker/src/entitlements/usage-snapshot.tslines 60-77 and prevents the 300% regression from returning.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/worker/src/entitlements/usage-snapshot.node.test.ts` around lines 104 - 117, Extend the usage snapshot tests around readEntitlementUsageSnapshot to cover non-counter resources: assert email_message_bytes with kind per_unit_max has percentOfLimit null and overEightyPercent false, and persistent_package_services with kind boolean_allowance has the same values. Keep the existing all-resources assertion and use the returned snapshot resource entries to verify both behaviors.packages/worker/client/routes/account-usage.tsx (1)
40-58: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winGroup and kind metadata is restated in three places instead of imported.
packages/worker/src/entitlements/resource-visibility.tsalready exportsEntitlementResourceGroup,EntitlementResourceVisibilityKind,entitlementResourceGroupOrder,entitlementResourceGroupLabels, andentitlementResourceGroupNotes. Three consumers redeclare the same values, so a new group or kind requires four coordinated edits and drift produces silently dropped rows or a validation error rather than a compile error.
packages/worker/client/routes/account-usage.tsx#L40-L58: importentitlementResourceGroupOrder,entitlementResourceGroupLabels, andentitlementResourceGroupNotesinstead of redefiningentitlementGroupOrder,entitlementGroupLabels, andentitlementGroupNotes. If a client bundle cannot import fromsrc/entitlements, re-export the three constants and both union types from#app/loader-data.tsand import them from there.packages/worker/src/app/loader-data.ts#L1273-L1276: replace the inline literal unions with the exportedEntitlementResourceGroupandEntitlementResourceVisibilityKindtypes.packages/worker/src/mcp/capabilities/account/usage-get.ts#L13-L14: derive both enums from the shared order and kind values, for examplez.enum(entitlementResourceGroupOrder), so a new group cannot fail output validation at runtime.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/worker/client/routes/account-usage.tsx` around lines 40 - 58, Centralize entitlement group and kind metadata across all three sites: in packages/worker/client/routes/account-usage.tsx lines 40-58, import and use entitlementResourceGroupOrder, entitlementResourceGroupLabels, and entitlementResourceGroupNotes instead of local definitions, re-exporting them and both union types through `#app/loader-data.ts` if client imports require it; in packages/worker/src/app/loader-data.ts lines 1273-1276, replace inline unions with EntitlementResourceGroup and EntitlementResourceVisibilityKind; in packages/worker/src/mcp/capabilities/account/usage-get.ts lines 13-14, derive both Zod enums from the shared group order and kind values.packages/worker/client/routes/account-billing.tsx (1)
568-572: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winReuse the server-provided usage href.
Line 498 links to usage through
billing.usageHref. This new link hardcodes the same path. Use one source so both links stay correct if the server changes the usage path.♻️ Proposed change
<p mix={css({ margin: 0 })}> - <a href="/account/usage" mix={css(primaryLinkCss)}> + <a href={billing.usageHref} mix={css(primaryLinkCss)}> See your current usage </a> </p>🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/worker/client/routes/account-billing.tsx` around lines 568 - 572, Update the usage link in account-billing.tsx to reuse the existing server-provided billing.usageHref value instead of hardcoding the /account/usage path. Keep the existing link styling and text, and make the new link follow the same source of truth as the other usage link so both stay aligned if the server-side route changes.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/worker/client/routes/account-usage.tsx`:
- Around line 356-364: Remove the literal period and following space between
item.whatCounts and item.howToReduce in the rendering span, so the existing
punctuation in whatCounts is not duplicated while preserving the separator
before howToReduce.
In `@packages/worker/src/entitlements/usage-snapshot.ts`:
- Around line 60-77: Update the percentOfLimit calculation in the usage snapshot
mapping to return null for both boolean_allowance and per_unit_max resources,
while preserving numeric percentage calculation for measurable limits and the
existing warning logic based on non-null percentages.
---
Nitpick comments:
In `@packages/worker/client/routes/account-billing.tsx`:
- Around line 568-572: Update the usage link in account-billing.tsx to reuse the
existing server-provided billing.usageHref value instead of hardcoding the
/account/usage path. Keep the existing link styling and text, and make the new
link follow the same source of truth as the other usage link so both stay
aligned if the server-side route changes.
In `@packages/worker/client/routes/account-usage.tsx`:
- Around line 40-58: Centralize entitlement group and kind metadata across all
three sites: in packages/worker/client/routes/account-usage.tsx lines 40-58,
import and use entitlementResourceGroupOrder, entitlementResourceGroupLabels,
and entitlementResourceGroupNotes instead of local definitions, re-exporting
them and both union types through `#app/loader-data.ts` if client imports require
it; in packages/worker/src/app/loader-data.ts lines 1273-1276, replace inline
unions with EntitlementResourceGroup and EntitlementResourceVisibilityKind; in
packages/worker/src/mcp/capabilities/account/usage-get.ts lines 13-14, derive
both Zod enums from the shared group order and kind values.
In `@packages/worker/src/entitlements/resource-visibility.ts`:
- Around line 142-159: Update accountUsageEntitlementResources to enforce
compile-time completeness against the full EntitlementResource union, not only
validate individual entries. Add a type-level check that fails when any
registered resource is omitted while preserving the existing ordered list and
EntitlementResource entry validation.
In `@packages/worker/src/entitlements/usage-snapshot.node.test.ts`:
- Around line 104-117: Extend the usage snapshot tests around
readEntitlementUsageSnapshot to cover non-counter resources: assert
email_message_bytes with kind per_unit_max has percentOfLimit null and
overEightyPercent false, and persistent_package_services with kind
boolean_allowance has the same values. Keep the existing all-resources assertion
and use the returned snapshot resource entries to verify both behaviors.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 7c2fe6c4-68ba-4baf-8780-7d9026b7b1ab
📒 Files selected for processing (11)
packages/worker/client/routes/account-billing.tsxpackages/worker/client/routes/account-usage.tsxpackages/worker/src/app/account-usage-data.node.test.tspackages/worker/src/app/account-usage-data.tspackages/worker/src/app/loader-data.tspackages/worker/src/entitlements/resource-visibility.tspackages/worker/src/entitlements/usage-snapshot.node.test.tspackages/worker/src/entitlements/usage-snapshot.tspackages/worker/src/mcp/capabilities/account/domain.tspackages/worker/src/mcp/capabilities/account/usage-get.node.test.tspackages/worker/src/mcp/capabilities/account/usage-get.ts
Co-authored-by: Kent C. Dodds <me+github@kentcdodds.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Makes it easy for a signed-in user to see what is affecting their entitlements:
/account/usage.json) now returns all 15 entitlement resources, each withgroup,kind,whatCounts,howToReduce,current,limit,percentOfLimit, andoverEightyPercent.packages/worker/client/routes/account-usage.tsx): resources grouped into daily rates (with UTC-midnight reset note), counts, storage, and per-item limits; progress bars; amber >80% warnings with upgrade links to/account/billing; per-resource plain-language guidance on what counts and how to reduce it (e.g. discard idle repo sessions — they are also swept automatically after 7 idle days).usage_getcapability on the account domain returning the same snapshot, so agents can answer "what's eating my quota".Key files
packages/worker/src/entitlements/resource-visibility.ts— visibility copy + resource orderingpackages/worker/src/entitlements/usage-snapshot.ts— shared snapshot readerpackages/worker/src/app/account-usage-data.ts— account loaderpackages/worker/client/routes/account-usage.tsx— usage page UIpackages/worker/src/mcp/capabilities/account/usage-get.ts— MCP capabilityTesting
npm run validategreen in the implementing environment (1,857 tests; one known-flakymeta_list_capabilitiestimeout passed on rerun). New tests:usage-snapshot.node.test.ts,usage-get.node.test.ts, updatedaccount-usage-data.node.test.ts.System recap — extends existing primitives (medium risk)
Mode: recap · Base:
main· Head:d26ae960Classification: extends — adds a user-facing read surface over the existing entitlements registry and a new self-scoped MCP capability; no enforcement changes.
Primitives touched
entitlementsapp-uicapability-registryusage_getaccount capabilitySystem map
The account usage page and the new
usage_getcapability both read one shared entitlement usage snapshot; no enforcement paths change.Legend: green = composes (wiring only) · amber = extended by this PR · red = new primitive · gray = context (unchanged, included only when an edge crosses it).
Conductor report
Implemented by the user-entitlement-visibility track; PR opened and shepherded by the conductor after the track's environment could not create PRs. Status: awaiting CI + CodeRabbit, then squash-merge.
Summary by CodeRabbit