cctally 1.7.3 → 1.8.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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
+- Extract leaf+mid kernel symbols (eprint, datetime/week helpers, alerts validation, open_db, make_week_ref, get_latest_usage_for_week) from `bin/cctally` into new `bin/_cctally_core.py`; rewrite ~200 sibling shim functions to honest top-level imports; the `c = _cctally()` accessor now survives only for residual Z-high cross-cutters (#50)
+
+### Fixed
+- `cctally blocks`: round-5 Bug J follow-up — `_load_recorded_five_hour_windows` now sorts `credit_moments` ascending before the inner credit-pick loop. The pre-fix loop broke on the first matching credit in `[next_bs, rs]` regardless of order; with two in-place credits inside the same pre-credit canonical 5h window and SQLite returning rows in insertion order (no `ORDER BY` on `week_reset_events`), pair `(A, B)` could latch onto credit_2 instead of credit_1, collapsing two distinct truncated anchors onto the same 10-minute floor and silently dropping one via override-map overwrite — re-introducing the phantom heuristic `~` row Bug J was meant to eliminate. Sorting once ensures the break consistently picks the earliest credit, which by construction is the one whose floor equals the next block's `block_start_at`. P2 (not seen in production; every observed in-place credit so far is one-per-week). Regressions: `tests/test_in_place_credit_detection.py::test_load_recorded_five_hour_windows_truncates_each_overlap_independently` (exercises reverse-time SQL order to prove the order-dependent bug) + `test_group_entries_into_blocks_no_phantom_between_two_credits` (renderer-side defense in depth — three canonical blocks render with `recorded` anchor and no `~` row in the gap). Issue [#44](https://github.com/omrikais/cctally-dev/issues/44).
+- `cctally record-usage`: in-place weekly credit race-defensive cleanup is now drift-tolerant. The DELETE that scrubs stale-replica snapshots out of the post-credit segment switched from strict `round(weekly_percent, 1) = round(prior_pct, 1)` equality to a `ABS(weekly_percent - ?) < 1.0` tolerance band around the observed pre-credit baseline. Today `claude-statusline` replays cctally's `hwm-7d` value byte-identically (its in-memory HWM equals the HWM we just wrote), so the existing strict predicate has worked — this is forward-looking defense. If Anthropic ever rounds the `--percent` payload differently from the OAuth API used by `record-usage`, or if `statusline` grows its own coarser rounding, a replay at e.g. `67.5` against a stored `prior_pct = 67.4` would slip past strict equality and then dominate the reset-aware clamp's MAX over the post-credit segment, masking legitimate post-credit values. 1.0pp band absorbs single-digit rounding drift; legitimate post-credit observations are ≥25pp away by the detection threshold's hypothesis so they're never caught. New schema migration `007_observed_pre_credit_pct` adds a nullable `observed_pre_credit_pct REAL` column to `week_reset_events`; the in-place credit INSERT stamps the value at write time so future cleanup tooling can re-derive the baseline without re-walking the snapshot stream. Simple `ALTER TABLE ADD COLUMN` — no UNIQUE constraint change, so no rename-recreate-copy (contrast migrations 005 / 006); live `CREATE TABLE` updated in lockstep so fresh installs land the new column directly via the dispatcher's fresh-install fast-stamp. Regression: `tests/test_in_place_credit_detection.py::test_credit_branch_cleanup_tolerates_rounding_drift` reproduces the drift scenario (stale replay at 67.5 vs prior_pct=67.4) — fails under strict-equality, passes under the band. P2 defensive hardening; not seen in production. Issue [#45](https://github.com/omrikais/cctally-dev/issues/45).
+- `cctally record-usage`: in-place 5h credit race-defensive cleanup is now drift-tolerant — symmetric follow-up to the weekly fix above. The DELETE that scrubs stale-replica snapshots out of the post-credit 5h segment switched from strict `round(five_hour_percent, 1) = round(prior_5h_pct, 1)` equality to a `ABS(five_hour_percent - ?) < 1.0` tolerance band around the observed pre-credit baseline. Pure predicate change — no migration needed because `five_hour_reset_events.prior_percent` (stamped at write time since v1.7.3, issue #43) already provides the durable pre-credit value that the weekly variant required migration 007 to add. Same forward-looking failure mode as the weekly path: if Anthropic ever rounds the `--five-hour-percent` payload differently from the OAuth API used by `record-usage`, or if `statusline` grows its own coarser rounding for the 5h dimension, a replay at e.g. `27.5` against a stored `prior_5h_pct = 27.4` would slip past strict equality and then dominate the reset-aware 5h clamp's MAX over the post-credit segment, masking legitimate post-credit 5h values. The 1.0pp band stays 4pp below the 5.0pp `_FIVE_HOUR_RESET_PCT_DROP_THRESHOLD` so legitimate post-credit observations (≥5pp away from `prior_5h_pct` by the detection threshold's hypothesis) are never caught. Regression: `tests/test_in_place_5h_credit_detection.py::test_credit_branch_5h_cleanup_tolerates_rounding_drift` reproduces the drift scenario (stale 27.5 replay vs `prior_5h_pct=27.4` → reset-aware 5h clamp masks the legitimate 4.0% post-credit seed up to 27.5 under strict equality; the band catches the replay and the seed lands). P2 defensive hardening; not seen in production. Issue [#48](https://github.com/omrikais/cctally-dev/issues/48).
+
 ## [1.7.3] - 2026-05-16
 
 ### Added

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_alerts.py

@@ -76,6 +76,14 @@ _build_alert_payload_weekly = _lib_alerts_payload._build_alert_payload_weekly
 _build_alert_payload_five_hour = _lib_alerts_payload._build_alert_payload_five_hour
 
 
+# === Honest imports from extracted homes ===================================
+# Spec 2026-05-17-cctally-core-kernel-extraction.md §3.3: kernel symbols
+# import from _cctally_core. `LOG_DIR` stays on the _cctally() accessor
+# per Q1=B (path constants propagate via monkeypatch.setitem against the
+# cctally namespace).
+from _cctally_core import now_utc_iso
+
+
 def _alerts_log_path() -> "pathlib.Path":
     """Return ``~/.local/share/cctally/logs/alerts.log`` (parent dirs created).
 
@@ -167,7 +175,7 @@ def _dispatch_alert_notification(
             or ""
         )
         line = (
-            f"{_cctally().now_utc_iso()}\t{axis}\t{payload.get('threshold')}\t{window_key}"
+            f"{now_utc_iso()}\t{axis}\t{payload.get('threshold')}\t{window_key}"
             f"\t{mode}\t{status}\n"
         )
         with open(log_path, "a") as f:
@@ -194,7 +202,6 @@ def cmd_alerts_test(args: argparse.Namespace) -> int:
       2  --threshold out of [1, 100] range
       3  other spawn error (PermissionError, OSError, ...)
     """
-    c = _cctally()
     axis = "weekly" if args.axis == "weekly" else "five_hour"
     threshold = int(args.threshold)
     if not (1 <= threshold <= 100):
@@ -206,7 +213,7 @@ def cmd_alerts_test(args: argparse.Namespace) -> int:
     if axis == "weekly":
         payload = _build_alert_payload_weekly(
             threshold=threshold,
-            crossed_at_utc=c.now_utc_iso(),
+            crossed_at_utc=now_utc_iso(),
             week_start_date=dt.date.today().isoformat(),
             cumulative_cost_usd=1.23,
             dollars_per_percent=0.01,
@@ -214,9 +221,9 @@ def cmd_alerts_test(args: argparse.Namespace) -> int:
     else:
         payload = _build_alert_payload_five_hour(
             threshold=threshold,
-            crossed_at_utc=c.now_utc_iso(),
+            crossed_at_utc=now_utc_iso(),
             five_hour_window_key=int(dt.datetime.now(dt.timezone.utc).timestamp()),
-            block_start_at=c.now_utc_iso(),
+            block_start_at=now_utc_iso(),
             block_cost_usd=1.23,
             primary_model="claude-sonnet-4-6",
         )

package/bin/_cctally_cache.py

@@ -118,17 +118,18 @@ def _cctally():
     return sys.modules["cctally"]
 
 
-# Module-level back-ref shims for the four bare-name helpers consumed
-# throughout the moved bodies. Each shim resolves
-# ``sys.modules['cctally'].X`` at CALL TIME (not bind time), so
-# monkeypatches on cctally's namespace propagate into the moved code
-# unchanged. Mirrors the precedent established in ``bin/_cctally_db.py``
-# (``now_utc_iso`` / ``parse_iso_datetime`` / ``_compute_block_totals``
-# / ``eprint`` shims).
-def eprint(*args, **kwargs):
-    return sys.modules["cctally"].eprint(*args, **kwargs)
-
-
+# === Honest imports from extracted homes ===================================
+# Spec 2026-05-17-cctally-core-kernel-extraction.md §3.3: kernel symbols
+# (Z-leaf + Z-mid) import from _cctally_core. The legacy shim function
+# for ``eprint`` is deleted.
+from _cctally_core import eprint
+
+
+# Module-level back-ref shims for the three out-of-scope JSONL/project
+# discovery helpers that STAY in bin/cctally per spec §3.7. Each shim
+# resolves ``sys.modules['cctally'].X`` at CALL TIME (not bind time),
+# so monkeypatches on cctally's namespace propagate into the moved code
+# unchanged.
 def _decode_escaped_cwd(*args, **kwargs):
     return sys.modules["cctally"]._decode_escaped_cwd(*args, **kwargs)
 

package/bin/_cctally_config.py

@@ -48,6 +48,25 @@ def _cctally():
     return sys.modules["cctally"]
 
 
+# === Honest imports from extracted homes ===================================
+# Spec 2026-05-17-cctally-core-kernel-extraction.md §3.3: kernel symbols
+# import from _cctally_core; the Bucket-X helper `normalize_display_tz_value`
+# imports from `_lib_display_tz`. Path constants (`CONFIG_PATH`,
+# `CONFIG_LOCK_PATH`) plus out-of-scope validators
+# (`_normalize_alerts_enabled_value`, `_validate_dashboard_bind_value`,
+# `_validate_update_check_ttl_hours_value`, `_normalize_update_check_enabled_value`,
+# `get_display_tz_pref`, `UPDATE_DEFAULT_TTL_HOURS`) stay on the
+# _cctally() accessor.
+from _cctally_core import (
+    eprint,
+    ensure_dirs,
+    DEFAULT_WEEK_START,
+    _get_alerts_config,
+    _AlertsConfigError,
+)
+from _lib_display_tz import normalize_display_tz_value
+
+
 _CONFIG_CORRUPT_WARNED = False  # one-shot warn flag for load_config
 
 
@@ -61,20 +80,19 @@ def _warn_config_corrupt_once(reason: str) -> None:
         return
     _CONFIG_CORRUPT_WARNED = True
     c = _cctally()
-    c.eprint(
+    eprint(
         f"warning: ignoring corrupt {c.CONFIG_PATH} ({reason}); "
         "using in-memory defaults"
     )
 
 
 def _default_config_data() -> dict[str, Any]:
-    c = _cctally()
     return {
         "collector": {
             "host": "127.0.0.1",
             "port": 17321,
             "token": secrets.token_hex(16),
-            "week_start": c.DEFAULT_WEEK_START,
+            "week_start": DEFAULT_WEEK_START,
         }
     }
 
@@ -122,7 +140,7 @@ def config_writer_lock():
     either the pre-rename or post-rename file, never partial bytes.
     """
     c = _cctally()
-    c.ensure_dirs()
+    ensure_dirs()
     c.CONFIG_LOCK_PATH.touch()
     fh = open(c.CONFIG_LOCK_PATH, "w")
     try:
@@ -154,7 +172,7 @@ def load_config() -> dict[str, Any]:
     #17 fix).
     """
     c = _cctally()
-    c.ensure_dirs()
+    ensure_dirs()
     parsed = _try_read_config()
     if parsed is not None:
         return parsed
@@ -186,8 +204,7 @@ def _load_config_unlocked() -> dict[str, Any]:
     do its own save_config call atomically. Corrupt-file path returns
     in-memory defaults (caller's save will overwrite cleanly).
     """
-    c = _cctally()
-    c.ensure_dirs()
+    ensure_dirs()
     parsed = _try_read_config()
     if parsed is not None:
         return parsed
@@ -208,7 +225,7 @@ def save_config(data: dict[str, Any]) -> None:
     not the read-modify-write semantics of `cctally config set`.
     """
     c = _cctally()
-    c.ensure_dirs()
+    ensure_dirs()
     payload = (json.dumps(data, indent=2) + "\n").encode("utf-8")
     tmp = c.CONFIG_PATH.with_name(f"{c.CONFIG_PATH.name}.tmp.{os.getpid()}")
     fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o644)
@@ -248,7 +265,7 @@ def cmd_config(args: argparse.Namespace) -> int:
         return _cmd_config_set(args)
     if action == "unset":
         return _cmd_config_unset(args)
-    c.eprint(f"cctally config: unknown action {action!r}")
+    eprint(f"cctally config: unknown action {action!r}")
     return 2
 
 
@@ -265,7 +282,7 @@ def _config_known_value(config: dict, key: str) -> "object":
     if key == "display.tz":
         return c.get_display_tz_pref(config)
     if key == "alerts.enabled":
-        return bool(c._get_alerts_config(config)["enabled"])
+        return bool(_get_alerts_config(config)["enabled"])
     if key == "dashboard.bind":
         # Default semantic alias is 'loopback' (resolves to 127.0.0.1 at
         # bind time). LAN exposure is opt-in via `set dashboard.bind lan`
@@ -306,10 +323,9 @@ def _config_known_value(config: dict, key: str) -> "object":
 
 
 def _cmd_config_get(args: argparse.Namespace, config: dict) -> int:
-    c = _cctally()
     key = args.key
     if key is not None and key not in ALLOWED_CONFIG_KEYS:
-        c.eprint(f"cctally config: unknown config key {key!r}")
+        eprint(f"cctally config: unknown config key {key!r}")
         return 2
     pairs: "list[tuple[str, object]]" = []
     if key is None:
@@ -350,13 +366,13 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
     c = _cctally()
     key, raw = args.key, args.value
     if key not in ALLOWED_CONFIG_KEYS:
-        c.eprint(f"cctally config: unknown config key {key!r}")
+        eprint(f"cctally config: unknown config key {key!r}")
         return 2
     if key == "display.tz":
         try:
-            canonical = c.normalize_display_tz_value(raw)
+            canonical = normalize_display_tz_value(raw)
         except ValueError:
-            c.eprint(f"cctally config: invalid IANA zone {raw!r}")
+            eprint(f"cctally config: invalid IANA zone {raw!r}")
             return 2
         with config_writer_lock():
             config = _load_config_unlocked()
@@ -399,8 +415,8 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
             # Validate the would-be merged block before persisting so
             # we never write a config that fails subsequent reads.
             try:
-                c._get_alerts_config({**config, "alerts": alerts_block})
-            except c._AlertsConfigError as exc:
+                _get_alerts_config({**config, "alerts": alerts_block})
+            except _AlertsConfigError as exc:
                 print(f"cctally: alerts config error: {exc}", file=sys.stderr)
                 return 2
             config["alerts"] = alerts_block
@@ -489,10 +505,9 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
 
 
 def _cmd_config_unset(args: argparse.Namespace) -> int:
-    c = _cctally()
     key = args.key
     if key not in ALLOWED_CONFIG_KEYS:
-        c.eprint(f"cctally config: unknown config key {key!r}")
+        eprint(f"cctally config: unknown config key {key!r}")
         return 2
     if key == "display.tz":
         with config_writer_lock():