cctally 1.7.4 → 1.8.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.8.0] - 2026-05-18
+
+### Added
+- dashboard envelope: new `daily.total_cost_usd` and `daily.total_tokens` fields exposed alongside the existing `daily.rows[]` so `DailyPanel` and downstream consumers can read the panel's total from the envelope instead of summing rows client-side. Backward-compatible additive change — consumers that ignore the new fields keep working. Sourced from the new `DailyView.total_cost_usd` / `DailyView.total_tokens` view-model fields populated by `build_daily_view` at envelope-construction time.
+
+### Changed
+- view-model kernel: introduce `bin/_lib_view_models.py` as the single canonical builder for each report command's render dataset — adds `DailyView` + `build_daily_view`, `MonthlyView` + `build_monthly_view`, `WeeklyView` + `build_weekly_view`, `TrendView` + `build_trend_view`, and `SessionsView` + `build_sessions_view`. CLI consumers (`cmd_daily`, `cmd_monthly`, `cmd_weekly`, `cmd_report`, `cmd_session`), dashboard envelope builders (`_dashboard_build_*`), share-output snapshots (`_build_*_snapshot`), and TUI builders (`_tui_build_*`) now all route through the same kernel instead of re-aggregating from `iter_entries()` independently. Collapses the prior 3× re-totaling cost across CLI / dashboard / share for daily, monthly, weekly, and sessions; downstream renderers consume the dataclass directly and the camelCase dict workaround between `cmd_report` and the dashboard trend panel is removed. Refactor-only externally — behavior changes are limited to the additive envelope fields above and the credit-week footer fix below.
+- Refine npm package description and README header for discoverability: front-load high-intent search terms ("Claude Code usage tracker", "dashboard", "Pro/Max subscription limits", "quota forecasts", "ccusage-compatible") while preserving the distinctive "cost-per-percent trend" hook. Swap five `package.json` keywords — drop generic noise (`usage`, `cost`, `tracker`, `llm`, `ai-tools`) and add high-intent terms (`claude-code-dashboard`, `claude-code-quota`, `claude-code-cost`, `ccusage-alternative`, `quota-tracking`). GitHub repo About and topics updated to match in lockstep. Description re-indexes on npm at next publish.
+
+### Fixed
+- dashboard weekly panel: footer total now matches the synthesized rows on credit weeks. Pre-fix, the panel's row list included `_apply_midweek_reset_override`'s synthesized pre-credit + post-credit rows split at `effective_reset_at_utc`, but the footer total was read from `weekly_cost_snapshots.cost_usd` (the snapshotted total over the original whole week), so the displayed rows summed to a different number than the footer. Now the footer reads `WeeklyView.total_cost_usd`, which sums over the same synthesized rows the panel renders, so the two always match by construction.
+
 ## [1.7.4] - 2026-05-17
 
 ### Changed

package/README.md

@@ -6,7 +6,7 @@
 </p>
 
 <p align="center">
-  <strong>Track Claude Code subscription usage as a weekly $-per-1% trend. Local web dashboard, terminal UI, forecasts, and threshold alerts.</strong>
+  <strong>Claude Code usage tracker and local dashboard for Pro/Max subscription limits - weekly cost-per-percent trend, quota forecasts, threshold alerts. ccusage-compatible.</strong>
 </p>
 
 <p align="center">

package/bin/_cctally_dashboard.py

@@ -1719,10 +1719,14 @@ def _dashboard_build_monthly_periods(conn: "sqlite3.Connection",
                                      display_tz: "ZoneInfo | None" = None) -> "list[MonthlyPeriodRow]":
     """Latest n calendar months as MonthlyPeriodRow, newest-first.
 
-    Builds via `_aggregate_monthly` over the trailing window
-    [now_utc - n calendar months, now_utc]. Bucketing and `is_current`
-    label both follow `display_tz` so users on a non-host display zone
-    see months grouped consistently with the rest of the UI.
+    Thin wrapper around ``build_monthly_view`` (spec §6.2). The view
+    owns the aggregator call, boundary-spillover drop, delta_cost_pct
+    derivation, and ``is_current`` flagging — this function just
+    fetches the trailing window of entries and returns ``view.rows``.
+
+    The sync thread separately captures ``view.total_cost_usd`` /
+    ``view.total_tokens`` for the envelope; see
+    ``_tui_build_snapshot`` and ``DataSnapshot.monthly_total_*``.
     """
     # Compute window start = first day of the month that is (n - 1) months
     # before the current month. _aggregate_monthly walks all entries and
@@ -1741,44 +1745,10 @@ def _dashboard_build_monthly_periods(conn: "sqlite3.Connection",
     range_end = now_utc
 
     entries = get_entries(range_start, range_end, skip_sync=skip_sync)
-    buckets = _aggregate_monthly(entries, mode="auto", tz=display_tz)
-    # Reverse for newest-first AND cap to n BEFORE the delta loop. In tzs
-    # west of UTC, `range_start` (UTC midnight on the 1st) lands in the
-    # PREVIOUS local month, so entries in the boundary window get bucketed
-    # as a (n+1)th `'YYYY-MM'` row. Slicing here drops that partial bucket,
-    # which (a) keeps the visible history at the requested length and
-    # (b) makes the oldest visible row's delta `None` (prev = None) rather
-    # than a wildly wrong delta vs. a few-hour spillover bucket.
-    buckets = list(reversed(buckets))[:n]
-    rows: list[MonthlyPeriodRow] = []
-    # `_aggregate_monthly` keys buckets by `display_tz` (or local-tz when
-    # unset) month. Mirror that here so `is_current` matches even when
-    # now_utc straddles a tz month boundary (e.g. 23:30 UTC on the last
-    # of the month in a UTC+1 zone).
-    cur_label = (
-        now_utc.astimezone(display_tz) if display_tz is not None
-        # internal fallback: host-local intentional
-        else now_utc.astimezone()
-    ).strftime("%Y-%m")
-    for i, b in enumerate(buckets):
-        # b.bucket is the YYYY-MM string for monthly aggregation.
-        prev = buckets[i + 1] if i + 1 < len(buckets) else None
-        delta = None
-        if prev is not None and prev.cost_usd > 0:
-            delta = (b.cost_usd - prev.cost_usd) / prev.cost_usd
-        rows.append(MonthlyPeriodRow(
-            label=b.bucket,
-            cost_usd=b.cost_usd,
-            total_tokens=b.total_tokens,
-            input_tokens=b.input_tokens,
-            output_tokens=b.output_tokens,
-            cache_creation_tokens=b.cache_creation_tokens,
-            cache_read_tokens=b.cache_read_tokens,
-            delta_cost_pct=delta,
-            is_current=(b.bucket == cur_label),
-            models=_model_breakdowns_to_models(b.model_breakdowns, b.cost_usd),
-        ))
-    return rows
+    c = _cctally()
+    view = c.build_monthly_view(entries, now_utc=now_utc, n=n,
+                                 display_tz=display_tz)
+    return list(view.rows)
 
 
 def _dashboard_build_weekly_periods(conn: "sqlite3.Connection",
@@ -1787,10 +1757,15 @@ def _dashboard_build_weekly_periods(conn: "sqlite3.Connection",
                                     skip_sync: bool = False) -> "list[WeeklyPeriodRow]":
     """Latest n subscription weeks as WeeklyPeriodRow, newest-first.
 
-    Mirrors the bucket+overlay path used by `cmd_weekly`, scoped to a
-    trailing 84-day window (12 weeks plus slack). Boundaries come from
-    `_compute_subscription_weeks`; usage % comes from
-    `weekly_usage_snapshots` via `get_latest_usage_for_week`.
+    Thin builder-using prelude + Bug-K pre-credit synthesis on top of
+    ``view.rows``. ``build_weekly_view`` (in ``bin/_lib_view_models.py``)
+    owns the bucket+overlay walk — this function calls it, swaps two
+    presentation fields (``label`` ← ``display_start_date`` for post-
+    early-reset weeks; ``is_current`` ← SubWeek-containing-now_utc with
+    snapshot fallback so the "Now" pill tracks wall time), layers Bug-K
+    pre-credit synthesized rows over the natural rows, then recomputes
+    ``delta_cost_pct`` newest-first so the synthesized rows participate
+    in the deltas.
 
     Note: weekly bucketing intentionally does NOT take ``display_tz`` —
     SubWeek bucket keys come from server-anchored stored anchors and the
@@ -1808,10 +1783,6 @@ def _dashboard_build_weekly_periods(conn: "sqlite3.Connection",
         parse_iso_datetime(weeks[0].start_ts, "week_start_at"),
     )
     entries = get_entries(fetch_start, range_end, skip_sync=skip_sync)
-    buckets = _aggregate_weekly(entries, weeks)
-    if not buckets:
-        return []
-
     as_of_utc = (
         range_end.astimezone(dt.timezone.utc)
         .replace(microsecond=0)
@@ -1819,6 +1790,15 @@ def _dashboard_build_weekly_periods(conn: "sqlite3.Connection",
         .replace("+00:00", "Z")
     )
 
+    # Builder prelude: produce the natural newest-first rows + overlay.
+    c = _cctally()
+    view = c.build_weekly_view(
+        conn, entries, weeks=weeks, now_utc=now_utc,
+        display_tz=None, as_of_utc=as_of_utc,
+    )
+    if not view.rows:
+        return []
+
     # Prefer the SubWeek that actually contains `now_utc` so the "Now" pill
     # tracks wall time even when `weekly_usage_snapshots` is stale (e.g.,
     # status line hasn't fired yet this week but cost entries already exist).
@@ -1843,47 +1823,36 @@ def _dashboard_build_weekly_periods(conn: "sqlite3.Connection",
         else:
             cur_week_start = max(weeks, key=lambda w: w.start_date).start_date.isoformat()
 
+    # SubWeek lookup by (start_ts, end_ts) — the builder identifies each row
+    # by these ISO strings on ``WeeklyPeriodRow``, which match SubWeek 1:1
+    # post _aggregate_weekly invariant.
+    sw_by_window = {(w.start_ts, w.end_ts): w for w in weeks}
+
+    # Convert builder rows (newest-first) → oldest-first so the existing
+    # Bug-K insertion logic (oldest-first indices) stays unchanged. Override
+    # the two presentation fields that diverge between CLI/share (which use
+    # ``start_date`` + "now in window" semantics) and the dashboard panel
+    # (which uses ``display_start_date`` + "current SubWeek" semantics).
     rows_oldest_first: list[WeeklyPeriodRow] = []
-    for bucket in buckets:
-        sw = next(w for w in weeks if w.start_date.isoformat() == bucket.bucket)
-        # Label = MM-DD of the week's display_start_date — for non-reset
-        # weeks this equals start_date; for post-early-reset weeks the
-        # post-processor shifts it forward to the effective reset moment
-        # so the user sees the date the week actually began (04-23 vs the
-        # API-derived backdated 04-18).
-        label = sw.display_start_date.strftime("%m-%d")
-        ref = make_week_ref(
-            week_start_date=sw.start_date.isoformat(),
-            week_end_date=sw.end_date.isoformat(),
-            week_start_at=sw.start_ts,
-            week_end_at=sw.end_ts,
-        )
-        usage_row = get_latest_usage_for_week(conn, ref, as_of_utc=as_of_utc)
-        used_pct = None
-        dpp = None
-        if usage_row is not None and usage_row["weekly_percent"] is not None:
-            used_pct = float(usage_row["weekly_percent"])
-            dpp = (bucket.cost_usd / used_pct) if used_pct > 0 else None
-        rows_oldest_first.append(WeeklyPeriodRow(
-            label=label,
-            cost_usd=bucket.cost_usd,
-            total_tokens=bucket.total_tokens,
-            input_tokens=bucket.input_tokens,
-            output_tokens=bucket.output_tokens,
-            cache_creation_tokens=bucket.cache_creation_tokens,
-            cache_read_tokens=bucket.cache_read_tokens,
-            used_pct=used_pct,
-            dollar_per_pct=dpp,
-            delta_cost_pct=None,  # filled below in newest-first pass
+    for r in reversed(view.rows):
+        sw = sw_by_window.get((r.week_start_at, r.week_end_at))
+        if sw is not None:
+            # Label = MM-DD of the week's display_start_date — for non-reset
+            # weeks this equals start_date; for post-early-reset weeks the
+            # post-processor shifts it forward to the effective reset moment
+            # so the user sees the date the week actually began (04-23 vs the
+            # API-derived backdated 04-18).
+            r.label = sw.display_start_date.strftime("%m-%d")
             # is_current keys on start_date (the bucket / lookup key) on both
             # sides of the comparison; display_start_date may diverge for
             # reset-event weeks but that is intentional — display vs. lookup
             # are kept separate.
-            is_current=(sw.start_date.isoformat() == cur_week_start),
-            models=_model_breakdowns_to_models(bucket.model_breakdowns, bucket.cost_usd),
-            week_start_at=sw.start_ts,
-            week_end_at=sw.end_ts,
-        ))
+            r.is_current = (sw.start_date.isoformat() == cur_week_start)
+        # delta_cost_pct: builder computed it in asc order; reset and
+        # recompute newest-first below AFTER Bug-K rows merge in, so the
+        # synthesized rows participate in the deltas.
+        r.delta_cost_pct = None
+        rows_oldest_first.append(r)
 
     # Bug K (v1.7.2 round-5): synthesize a pre-credit segment row for
     # each in-place credit event. Without this the credited week shows
@@ -2250,27 +2219,51 @@ def _dashboard_build_daily_panel(conn: "sqlite3.Connection",
                                   display_tz: "ZoneInfo | None" = None) -> "list[DailyPanelRow]":
     """Latest n display-tz dates as DailyPanelRow, newest-first.
 
-    Mirrors `_dashboard_build_monthly_periods`: walks a wide trailing
-    window, runs `_aggregate_daily`, reverses to newest-first, caps to
-    `n`, then computes intensity buckets in-place. Bucketing and the
-    `is_today` reference both follow `display_tz` so users on a
-    non-host display zone see days grouped consistently with the rest
-    of the UI.
+    Two-layer composition (spec §4.4, §6.1):
+
+    1. ``build_daily_view`` (in ``bin/_lib_view_models.py``) is the
+       data plane — gap-free rows + totals derived from the
+       aggregator output.
+    2. This function is the presentation adapter — materializes the
+       contiguous N-day calendar window (gap days as zero-cost rows
+       so the heatmap shows them as faded cells), fills the
+       presentation-only ``label`` (``MM-DD``) and
+       ``intensity_bucket`` (quintile via
+       ``_compute_intensity_buckets``) fields.
+
+    Bucketing and the ``is_today`` reference both follow
+    ``display_tz`` so users on a non-host display zone see days
+    grouped consistently with the rest of the UI.
+
+    Sync-thread totals: the caller sums over the materialized rows
+    this function returns and stashes the result on
+    ``DataSnapshot.daily_total_cost_usd`` / ``daily_total_tokens`` for
+    the envelope adapter. Sum-over-visible-rows preserves the
+    structural-equality invariant the dashboard footer reads
+    (`total === rows.reduce(...)`); gap days carry ``cost_usd=0.0`` /
+    ``total_tokens=0`` so the sum stays gap-free semantically. Doing
+    it at the sync-thread site keeps this function's return type
+    stable (preserving the dashboard / TUI / test fixture monkeypatch
+    surface that consumes a plain ``list[DailyPanelRow]``).
     """
     # Wide trailing window — n days of slack on either side keeps it
     # forgiving of tz boundary issues.
     range_start = now_utc - dt.timedelta(days=n + 1)
     range_end = now_utc
     entries = get_entries(range_start, range_end, skip_sync=skip_sync)
-    buckets = _aggregate_daily(entries, mode="auto", tz=display_tz)
-    if not buckets:
+
+    c = _cctally()
+    view = c.build_daily_view(entries, now_utc=now_utc,
+                              display_tz=display_tz)
+    if not view.rows:
         return []
 
-    # Materialize the full n-day calendar window so gap days render as
-    # zero-cost h0 cells (and today always appears, even on idle days).
-    # _aggregate_daily only emits buckets for dates with entries, so we
-    # overlay them onto a contiguous newest-first range.
-    buckets_by_date = {b.bucket: b for b in buckets}
+    # Materialize the contiguous N-day window. ``view.rows`` is gap-free
+    # (newest-first) and carries the data-plane fields; the adapter
+    # overlays it onto the calendar window and fills the presentation-
+    # only ``label`` / ``intensity_bucket`` (which the builder left at
+    # dataclass defaults per spec §4.4).
+    rows_by_date = {r.date: r for r in view.rows}
     today_local = (
         now_utc.astimezone(display_tz) if display_tz is not None
         # internal fallback: host-local intentional
@@ -2281,28 +2274,12 @@ def _dashboard_build_daily_panel(conn: "sqlite3.Connection",
     for i in range(n):
         d = today_local - dt.timedelta(days=i)
         date_str = d.isoformat()
-        b = buckets_by_date.get(date_str)
-        if b is not None:
-            # cache_read / (input + cache_creation + cache_read) — same ratio
-            # used by Block / Session / TuiSession dashboard surfaces. Do NOT
-            # switch to the diff-metrics formula (cache_read / (cache_read +
-            # input)) without aligning all dashboard surfaces.
-            denom = b.input_tokens + b.cache_creation_tokens + b.cache_read_tokens
-            cache_hit = (b.cache_read_tokens / denom * 100.0) if denom > 0 else None
-            rows.append(DailyPanelRow(
-                date=date_str,
-                label=date_str[5:],  # YYYY-MM-DD → MM-DD
-                cost_usd=b.cost_usd,
-                is_today=(d == today_local),
-                intensity_bucket=0,  # set by _compute_intensity_buckets below
-                models=_model_breakdowns_to_models(b.model_breakdowns, b.cost_usd),
-                input_tokens=b.input_tokens,
-                output_tokens=b.output_tokens,
-                cache_creation_tokens=b.cache_creation_tokens,
-                cache_read_tokens=b.cache_read_tokens,
-                total_tokens=b.total_tokens,
-                cache_hit_pct=cache_hit,
-            ))
+        existing = rows_by_date.get(date_str)
+        if existing is not None:
+            # Use the view-model row but fill the presentation-only
+            # ``label`` (intensity_bucket is set by
+            # ``_compute_intensity_buckets`` below).
+            rows.append(dataclasses.replace(existing, label=date_str[5:]))
         else:
             # Zero-cost gap day: tokens default to 0, cache_hit_pct to None
             # (avoids /0 and signals 'no data' cleanly to the modal tile).
@@ -2877,8 +2854,28 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
     # can distinguish "loading / not synced yet" (null parent) from
     # "synced + no data" (empty rows). For Weekly/Monthly, sync always
     # builds the rows list (even if empty), so we always emit the object.
-    weekly_env = {"rows": [_weekly_row_to_dict(r) for r in snap.weekly_periods]}
-    monthly_env = {"rows": [_monthly_row_to_dict(r) for r in snap.monthly_periods]}
+    weekly_env = {
+        "rows": [_weekly_row_to_dict(r) for r in snap.weekly_periods],
+        # View-model unification (Bundle 1; spec §6.6): pre-computed
+        # totals. Sourced from sum-over-visible-rows in the sync thread
+        # (``_tui_build_snapshot``) so the footer total is structurally
+        # equal to the React panel's ``rows.reduce(...)``. The earlier
+        # ``build_weekly_view``-sourced totals undercounted Bug-K
+        # pre-credit synthesized rows on credit weeks; the regression is
+        # captured by
+        # ``test_weekly_envelope_total_matches_sum_of_visible_rows``.
+        "total_cost_usd": snap.weekly_total_cost_usd,
+        "total_tokens":   snap.weekly_total_tokens,
+    }
+    monthly_env = {
+        "rows": [_monthly_row_to_dict(r) for r in snap.monthly_periods],
+        # View-model unification (Bundle 1; spec §6.6): pre-computed
+        # totals via sum-over-visible-rows so the React MonthlyPanel's
+        # smoking-gun ``rows.reduce(...)`` collapses to a single envelope
+        # read with the structural-equality invariant preserved.
+        "total_cost_usd": snap.monthly_total_cost_usd,
+        "total_tokens":   snap.monthly_total_tokens,
+    }
 
     blocks_env = {"rows": [_blocks_row_to_dict(r) for r in snap.blocks_panel]}
 
@@ -2898,6 +2895,15 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         "rows":                [_daily_row_to_dict(r) for r in daily_rows],
         "quantile_thresholds": daily_thresholds,
         "peak":                daily_peak,
+        # View-model unification (Bundle 1; spec §6.6): pre-computed
+        # totals via sum-over-visible-rows in the sync thread. Gap days
+        # carry ``cost_usd=0.0`` and ``total_tokens=0`` so summing the
+        # materialized panel rows preserves the gap-free semantics. The
+        # React panel's `rows.reduce(...)` collapses to a single
+        # envelope read with the structural-equality invariant
+        # preserved.
+        "total_cost_usd":      snap.daily_total_cost_usd,
+        "total_tokens":        snap.daily_total_tokens,
     }
 
     # ---- threshold-actions T5: alerts envelope + settings mirror ----
@@ -3099,6 +3105,12 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
                     }
                     for w in (snap.weekly_history or [])
                 ],
+                # View-model unification (Bundle 1; spec §6.6): the
+                # pre-computed 3-sample $/% mean. TrendPanel can stop
+                # re-deriving the panel-average; TrendModal's median
+                # over trend.history is out of scope for this refactor
+                # (separate dataset, separate follow-up).
+                "avg_dollars_per_pct": snap.trend_avg_dollars_per_pct,
             },
 
         "weekly":  weekly_env,