Skip to content

feat(reports): one JSON envelope across cmduse, ocuse and arkuse - #17

Merged
JeffreyJYZ merged 1 commit into
mainfrom
feat/report-envelope-parity
Nov 13, 2026
Merged

JeffreyJYZ merged 1 commit into
mainfrom
feat/report-envelope-parity

Conversation

@jyzbot

@jyzbot jyzbot commented Nov 13, 2026

Copy link
Copy Markdown
Collaborator

PR #16 merged first, so the dashboard panel is on main. This closes the remaining axis: the report envelopes.

What diverged (measured, after #16)

### daily     cmduse days,scope,total           ocuse/arkuse days,scope,source,total
### hourly    cmduse hours,scope,source         ocuse/arkuse hours,scope,source,total
### model     cmduse models,since,source        ocuse/arkuse models,scope,sinceMs,source
### session   cmduse projects                    ocuse/arkuse scope,sessions,source

After

### daily     days,scope,source,total                         (all three)
### hourly    hours,scope,source,total                        (all three)
### model     models,scope,since,sinceMs,source               (all three)
### session   projects,scope,sessions,source                  (all three)

Naming choices, so nothing breaks:

  • since stays — mpc's --usage contract reads {source, since, models} from cmduse model --json; sinceMs is added beside it rather than replacing it.
  • sessions and projects both appear on session --json, identical rows; cmduse spelled it projects first, ocuse/arkuse sessions, so both names exist instead of renaming either.
  • source names the origin (command-code, opencode, local), which is what lets a consumer read one shape.

Other axes, already clean

subcommands   -1 config daily hourly mcp model models plans session statusline   (identical)
mcp tools     daily,hourly,model,models,plans,session,usage                      (identical)
flags         only the source-forced set diverges: --local (cmduse), --db/--no-api/
              --window/--period-start/--infer-anniversary (cmduse), --plan (ocuse/arkuse),
              --profile (arkuse) — exactly what AGENTS.md documents
statusline    fiveHourSpent/Cap, weeklySpent/Cap, monthSpent/Cap on all three
-1 --json     source, periodStart/At, periodEnd/At, summary on all three

MCP tool arguments differ only where the source forces it (local, tz on cmduse; plan on ocuse/arkuse), and mcp_tests::tool_params pins that sorted set per binary — 28 tests pass.

Gates

cargo test -p cmd-usage      207 passed, 0 failed
cargo clippy --all-targets -D warnings   clean
cargo fmt --all -- --check    clean

Version 0.7.33. The envelope contract is now written into AGENTS.md beside the existing machine-readable-surface rule.

The three binaries disagreed on the report shape a consumer reads:

  daily    cmduse lacked source
  hourly   cmduse lacked total
  model    cmduse said since, the others sinceMs; cmduse lacked scope
  session  cmduse said projects, the others sessions

Every envelope now carries the same keys: daily/hourly {scope, source, total,
days|hours}, model {scope, source, since, sinceMs, models}, session both
'sessions' and 'projects' with identical rows. 'since' stays because mpc's
--usage contract reads it; 'sinceMs' is what ocuse/arkuse already emitted, so
both names exist rather than one being renamed out from under a consumer.

Flag, subcommand and MCP-tool parity were already clean; the only divergences
are the source-forced ones the repo documents.

Version 0.7.33.
@vercel

vercel Bot commented Nov 13, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
cmdcode-tools-site Ready Ready Preview Nov 13, 2026 3:55am UTC

@JeffreyJYZ
JeffreyJYZ merged commit 8527474 into main Nov 13, 2026
10 checks passed
@JeffreyJYZ
JeffreyJYZ deleted the feat/report-envelope-parity branch November 13, 2026 03:55
JeffreyJYZ added a commit that referenced this pull request Nov 13, 2026
The parity work in #17 was enforced by prose and an ad-hoc script. REPORT_*_KEYS
in report_render.rs is now the single contract, and each binary asserts its own
emitter against it (daily, hourly, model, session), so a key dropped from either
side fails all three tests.

Mutation-checked: shrinking REPORT_SESSION_KEYS to drop 'projects' fails the
cmduse and ocuse tests with the exact left/right key sets, and the suite returns
green when restored.

Test-only constants, so production code cannot read the contract back and agree
with itself.

Co-authored-by: Yizhou Jiang <yizhoujiang11@gmail.com>

This branch was successfully deployed

1 active deployment
Preview — 17382627 Deployed Nov 13, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants