cctally 1.21.2 → 1.22.0

package/bin/_cctally_dashboard.py

@@ -268,6 +268,9 @@ from _cctally_core import (
     make_week_ref,
     _get_alerts_config,
     _AlertsConfigError,
+    _get_budget_config,
+    _budget_alerts_active,
+    _BudgetConfigError,
 )
 from _lib_display_tz import (
     format_display_dt,
@@ -329,6 +332,10 @@ def _build_alert_payload_five_hour(*args, **kwargs):
     return sys.modules["cctally"]._build_alert_payload_five_hour(*args, **kwargs)
 
 
+def _build_alert_payload_budget(*args, **kwargs):
+    return sys.modules["cctally"]._build_alert_payload_budget(*args, **kwargs)
+
+
 def _dispatch_alert_notification(*args, **kwargs):
     return sys.modules["cctally"]._dispatch_alert_notification(*args, **kwargs)
 
@@ -4064,16 +4071,17 @@ def _build_alerts_envelope_array(
 ) -> list[dict]:
     """Return the ``alerts`` array for the SSE snapshot envelope.
 
-    Union of ``percent_milestones`` and ``five_hour_milestones`` rows
-    with ``alerted_at IS NOT NULL``, ordered newest-first by
-    ``alerted_at``, capped at ``limit`` (default 100). Single source of
-    truth for both the dashboard panel (slices to 10 client-side) and
-    the modal (renders all 100). Forward-only semantics: only rows the
-    alert-dispatch path stamped get included; pre-deploy crossings stay
-    NULL and are intentionally invisible (spec §4.3).
+    Union of ``percent_milestones``, ``five_hour_milestones``, and
+    ``budget_milestones`` rows with ``alerted_at IS NOT NULL``, ordered
+    newest-first by ``alerted_at``, capped at ``limit`` (default 100).
+    Single source of truth for both the dashboard panel (slices to 10
+    client-side) and the modal (renders all 100). Forward-only
+    semantics: only rows the alert-dispatch path stamped get included;
+    pre-deploy crossings stay NULL and are intentionally invisible
+    (spec §4.3).
 
-    Both axes share the same envelope schema; the ``axis`` field
-    discriminates.
+    All three axes share the same envelope schema; the ``axis`` field
+    (``weekly`` / ``five_hour`` / ``budget``) discriminates.
 
     Per-axis ``LIMIT`` is applied at the SQL level (each query may yield
     up to ``limit``) and the union is re-sorted + sliced — important for
@@ -4164,11 +4172,45 @@ def _build_alerts_envelope_array(
             },
         })
 
+    # Third axis (issue #19): equiv-$ budget threshold crossings. Budget
+    # alerts are keyed by the effective (post-reset) week_start_at + the
+    # integer threshold; the envelope id mirrors the dispatch payload's
+    # ``budget:<week_start_at>:<threshold>`` shape
+    # (``_build_alert_payload_budget``). No ``reset_event_id`` segment —
+    # a mid-week reset re-anchors ``week_start_at`` so the new window
+    # naturally gets fresh rows under ``UNIQUE(week_start_at, threshold)``.
+    budget_rows = conn.execute(
+        """
+        SELECT week_start_at, threshold, crossed_at_utc, alerted_at,
+               budget_usd, spent_usd, consumption_pct
+        FROM budget_milestones
+        WHERE alerted_at IS NOT NULL
+        ORDER BY alerted_at DESC
+        LIMIT ?
+        """,
+        (limit,),
+    ).fetchall()
+    for r in budget_rows:
+        threshold = int(r["threshold"])
+        out.append({
+            "id":         f"budget:{r['week_start_at']}:{threshold}",
+            "axis":       "budget",
+            "threshold":  threshold,
+            "crossed_at": r["crossed_at_utc"],
+            "alerted_at": r["alerted_at"],
+            "context": {
+                "week_start_at":   r["week_start_at"],
+                "budget_usd":      float(r["budget_usd"]),
+                "spent_usd":       float(r["spent_usd"]),
+                "consumption_pct": float(r["consumption_pct"]),
+            },
+        })
+
     # Python's list.sort is stable. When two alerts share the same
-    # `alerted_at` ISO string (rare; both axes firing within the same
-    # millisecond), the union order (weekly first, then 5h) determines
-    # the tiebreaker — no extra deterministic key is added because the
-    # spec doesn't require one.
+    # `alerted_at` ISO string (rare; multiple axes firing within the same
+    # millisecond), the union order (weekly, then 5h, then budget)
+    # determines the tiebreaker — no extra deterministic key is added
+    # because the spec doesn't require one.
     out.sort(key=lambda a: a["alerted_at"], reverse=True)
     return out[:limit]
 
@@ -4532,8 +4574,9 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
     # the entire snapshot — fall back to safe defaults and rely on
     # `_warn_alerts_bad_config_once` for the user-visible signal.
     alerts_array = list(getattr(snap, "alerts", []) or [])
+    _cfg_for_alerts = load_config()
     try:
-        _alerts_cfg = _get_alerts_config(load_config())
+        _alerts_cfg = _get_alerts_config(_cfg_for_alerts)
     except _AlertsConfigError as exc:
         _warn_alerts_bad_config_once(exc)
         _alerts_cfg = {
@@ -4541,10 +4584,21 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
             "weekly_thresholds": [],
             "five_hour_thresholds": [],
         }
+    # Budget is its OWN config block (issue #19) — source budget fields
+    # from ``_get_budget_config`` (the validated ``budget`` block), NOT
+    # the ``alerts`` block. Defensive: a corrupt budget block must not
+    # 500 the whole snapshot — fall back to "no budget / disabled".
+    try:
+        _budget_cfg = _get_budget_config(_cfg_for_alerts)
+    except _BudgetConfigError:
+        _budget_cfg = {"weekly_usd": None, "alerts_enabled": True,
+                       "alert_thresholds": []}
     alerts_settings = {
         "enabled":              _alerts_cfg["enabled"],
         "weekly_thresholds":    list(_alerts_cfg["weekly_thresholds"]),
         "five_hour_thresholds": list(_alerts_cfg["five_hour_thresholds"]),
+        "budget_thresholds":    list(_budget_cfg["alert_thresholds"]),
+        "budget_enabled":       _budget_alerts_active(_budget_cfg),
     }
 
     # Mirror update-state.json + update-suppress.json into the envelope
@@ -5126,9 +5180,11 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
 
         Body shape: ``{"display"?: {"tz": "..."}, "alerts"?: {...},
         "update"?: {"check"?: {"enabled"?: bool, "ttl_hours"?: int}},
-        "cache_report"?: {"anomaly_threshold_pp"?: int}}`` — every
-        top-level key is optional; any subset may be sent together
-        (combined save). Unknown top-level keys are rejected with 400.
+        "cache_report"?: {"anomaly_threshold_pp"?: int},
+        "budget"?: {"weekly_usd"?: number|null, "alerts_enabled"?: bool,
+        "alert_thresholds"?: int[]}}`` — every top-level key is optional;
+        any subset may be sent together (combined save). Unknown
+        top-level keys are rejected with 400.
 
         Per-block validation:
           * ``display.tz`` — "local", "utc", or a valid IANA zone (via
@@ -5147,6 +5203,10 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             ``{error, field: "anomaly_threshold_pp"}`` on out-of-range
             or non-int. Spec §6.1 hardcodes ``anomaly_window_days``;
             F10 tracks lifting that.
+          * ``budget`` — must be a dict; merged onto the persisted
+            ``budget`` block and validated via ``_get_budget_config(merged)``
+            (issue #19); ``_BudgetConfigError`` → 400. Budget is its OWN
+            config block, distinct from ``alerts``.
 
         Atomic merged write: if all touched blocks validate, the merged
         config is persisted in a single ``save_config`` call inside the
@@ -5198,7 +5258,9 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             return
 
         # Reject unknown top-level keys (forward-compat hygiene).
-        allowed_top_keys = {"display", "alerts", "update", "cache_report"}
+        allowed_top_keys = {
+            "display", "alerts", "update", "cache_report", "budget",
+        }
         for k in payload.keys():
             if k not in allowed_top_keys:
                 self._respond_json(
@@ -5212,12 +5274,13 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             and "alerts" not in payload
             and "update" not in payload
             and "cache_report" not in payload
+            and "budget" not in payload
         ):
             self._respond_json(
                 400,
                 {"error": (
                     "body must contain at least one of: "
-                    "display, alerts, update, cache_report"
+                    "display, alerts, update, cache_report, budget"
                 )},
             )
             return
@@ -5305,6 +5368,18 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 )
                 return
 
+        # Pre-validate budget shape (the structural type check; full
+        # cross-key validation runs inside the lock via
+        # ``_get_budget_config(merged)``). Budget is its OWN config block
+        # (issue #19), not part of ``alerts``.
+        if "budget" in payload:
+            budget_block = payload["budget"]
+            if not isinstance(budget_block, dict):
+                self._respond_json(
+                    400, {"error": "budget must be an object"}
+                )
+                return
+
         # Pre-validate update shape. Only `update.check.{enabled,ttl_hours}`
         # is settable today; any other key under `update` or `update.check`
         # is rejected so adding e.g. `update.banner.*` later is forward
@@ -5413,6 +5488,35 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                     self._respond_json(400, {"error": str(exc)})
                     return
 
+            if "budget" in payload:
+                # Same hand-edited-junk guard as alerts: a non-dict stored
+                # ``budget`` block in config.json should surface as a
+                # recoverable 400, not a 500. Budget is its OWN config
+                # block (issue #19); the inbound keys are
+                # ``weekly_usd`` / ``alerts_enabled`` / ``alert_thresholds``.
+                existing_budget = merged.get("budget")
+                if existing_budget is not None and not isinstance(
+                    existing_budget, dict
+                ):
+                    self._respond_json(
+                        400, {"error": "budget must be an object"}
+                    )
+                    return
+                merged_budget = dict(existing_budget or {})
+                budget_in = payload["budget"]
+                for leaf in ("weekly_usd", "alerts_enabled", "alert_thresholds"):
+                    if leaf in budget_in:
+                        merged_budget[leaf] = budget_in[leaf]
+                merged["budget"] = merged_budget
+                # Final validation against the merged block.
+                # _BudgetConfigError → 400 (no partial write — save_config
+                # has not yet been called).
+                try:
+                    _get_budget_config(merged)
+                except _BudgetConfigError as exc:
+                    self._respond_json(400, {"error": str(exc)})
+                    return
+
             if update_check_validated is not None:
                 # Same hand-edited-junk guard as alerts: a non-dict
                 # `update` or `update.check` block in config.json should
@@ -5473,6 +5577,19 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             )
         if "alerts" in payload:
             out["alerts"] = _get_alerts_config(merged)
+        if "budget" in payload:
+            # Echo the full validated budget block (defaults filled) so the
+            # SettingsOverlay can repaint without a follow-up GET.
+            validated_budget = _get_budget_config(merged)
+            out["budget"] = validated_budget
+            # Forward-only reconcile (mirrors `budget set` / `config set
+            # budget.*`): enabling/raising a budget while already past a
+            # threshold records the crossed thresholds as already-alerted so
+            # the next record-usage tick does NOT dispatch retroactive alerts.
+            # Runs AFTER save_config (config persisted first); best-effort —
+            # never breaks the 200 response. Config write already left the
+            # config_writer_lock, so the helper's open_db never nests.
+            _cctally()._reconcile_budget_on_config_write(validated_budget)
         if update_check_validated is not None:
             # Echo the full merged check block (cooked defaults included)
             # so the SettingsOverlay can repaint without a follow-up GET.
@@ -5523,8 +5640,9 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         ``_dispatch_alert_notification(..., mode="test")``, returns the
         dispatch status string in the JSON response.
 
-        Body (all fields optional): ``{"axis": "weekly"|"five_hour",
-        "threshold": 1..100}``. Defaults: axis="weekly", threshold=90.
+        Body (all fields optional): ``{"axis":
+        "weekly"|"five_hour"|"budget", "threshold": 1..100}``. Defaults:
+        axis="weekly", threshold=90.
 
         IMPORTANT: ``axis`` uses the underscore form (``"five_hour"``)
         in the JSON API to match the dispatch payload's internal axis
@@ -5563,11 +5681,12 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 return
 
         axis = body.get("axis", "weekly")
-        if axis not in ("weekly", "five_hour"):
+        if axis not in ("weekly", "five_hour", "budget"):
             self._respond_json(
                 400,
                 {"error": (
-                    f"axis must be 'weekly' or 'five_hour', got {axis!r}"
+                    "axis must be 'weekly', 'five_hour' or 'budget', "
+                    f"got {axis!r}"
                 )},
             )
             return
@@ -5592,6 +5711,19 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 cumulative_cost_usd=1.23,
                 dollars_per_percent=0.01,
             )
+        elif axis == "budget":
+            # Synthetic budget payload — mirrors the CLI cmd_alerts_test
+            # budget branch (NO DB writes, test/real divergence contract).
+            # spent scaled to the threshold so the body reads plausibly
+            # (e.g. 100% → $300 of $300).
+            payload = _build_alert_payload_budget(
+                threshold=threshold,
+                crossed_at_utc=now_utc_iso(),
+                week_start_at=dt.date.today().isoformat(),
+                budget_usd=300.0,
+                spent_usd=300.0 * threshold / 100.0,
+                consumption_pct=float(threshold),
+            )
         else:
             payload = _build_alert_payload_five_hour(
                 threshold=threshold,

package/bin/_cctally_db.py

@@ -1023,6 +1023,9 @@ _BANNER_SUPPRESSED_COMMANDS = frozenset({
     "doctor",          # consolidates migration + update banner state into its
                        # own report; double-printing the banner would duplicate
                        # findings doctor already surfaces structurally.
+    "pricing-check",   # read-only diagnostic emitting structured (often JSON)
+                       # output; banner noise pollutes the report + scripted
+                       # `--json` pipelines. Same posture as doctor.
     "repair-symlinks", # invoked by npm postinstall; no banner during install
     "blocks",          # stdout-formatted table replacing `ccusage blocks`;
                        # stderr noise pollutes the visually-aligned report and

package/bin/_cctally_record.py

@@ -171,6 +171,7 @@ from _cctally_core import (
     make_week_ref,
     _get_alerts_config,
     _AlertsConfigError,
+    _BudgetConfigError,
     _command_as_of,
 )
 from _lib_five_hour import _canonical_5h_window_key
@@ -258,6 +259,30 @@ def _build_alert_payload_five_hour(*args, **kwargs):
     return sys.modules["cctally"]._build_alert_payload_five_hour(*args, **kwargs)
 
 
+def _build_alert_payload_budget(*args, **kwargs):
+    return sys.modules["cctally"]._build_alert_payload_budget(*args, **kwargs)
+
+
+def _get_budget_config(*args, **kwargs):
+    return sys.modules["cctally"]._get_budget_config(*args, **kwargs)
+
+
+def _budget_alerts_active(*args, **kwargs):
+    return sys.modules["cctally"]._budget_alerts_active(*args, **kwargs)
+
+
+def _resolve_current_budget_window(*args, **kwargs):
+    return sys.modules["cctally"]._resolve_current_budget_window(*args, **kwargs)
+
+
+def _sum_cost_for_range(*args, **kwargs):
+    return sys.modules["cctally"]._sum_cost_for_range(*args, **kwargs)
+
+
+def insert_budget_milestone(*args, **kwargs):
+    return sys.modules["cctally"].insert_budget_milestone(*args, **kwargs)
+
+
 def _dispatch_alert_notification(*args, **kwargs):
     return sys.modules["cctally"]._dispatch_alert_notification(*args, **kwargs)
 
@@ -266,6 +291,10 @@ def _warn_alerts_bad_config_once(*args, **kwargs):
     return sys.modules["cctally"]._warn_alerts_bad_config_once(*args, **kwargs)
 
 
+def _warn_budget_bad_config_once(*args, **kwargs):
+    return sys.modules["cctally"]._warn_budget_bad_config_once(*args, **kwargs)
+
+
 def _get_oauth_usage_config(*args, **kwargs):
     return sys.modules["cctally"]._get_oauth_usage_config(*args, **kwargs)
 
@@ -644,6 +673,118 @@ def maybe_record_milestone(
         conn.close()
 
 
+def maybe_record_budget_milestone(saved: dict[str, Any]) -> None:
+    """Fire equiv-$ budget alerts on ACTUAL-spend threshold crossings
+    (Approach A — called from ``cmd_record_usage`` alongside the weekly-% /
+    5h-% milestone helpers). Gated, hot-path-cheap, set-then-dispatch,
+    fire-once. Errors are logged, not raised (the caller also wraps).
+
+    ``saved`` is accepted for call-site symmetry with
+    ``maybe_record_milestone`` / ``maybe_update_five_hour_block`` but is
+    unused: the budget window + live spend are resolved from the DB +
+    ``session_entries`` independently (a budget crossing depends on
+    cumulative equiv-$ spend, not on the just-recorded 7d-% snapshot).
+    """
+    # Gate FIRST (hot-path discipline): no budget or alerts off → zero
+    # overhead for non-budget users. `load_config()` is safe outside any
+    # writer lock — atomic-rename guarantees whole-byte reads. A malformed
+    # budget block is a quiet warn-once no-op (mirrors weekly/5h), NOT an
+    # unthrottled per-tick stderr via the caller's wrapper.
+    try:
+        budget_cfg = _get_budget_config(load_config())
+    except _BudgetConfigError as exc:
+        _warn_budget_bad_config_once(exc)
+        return
+    if not _budget_alerts_active(budget_cfg):
+        return
+    target = budget_cfg["weekly_usd"]
+    thresholds = budget_cfg["alert_thresholds"]
+    if not thresholds:
+        return
+
+    now_utc = _command_as_of()
+    pending_alerts: list[dict[str, Any]] = []
+    conn = open_db()
+    try:
+        window = _resolve_current_budget_window(conn, now_utc)
+        if window is None:
+            return  # no resolvable week window yet (spec §6 worst case)
+        week_start_at, _week_end_at = window
+        week_key = week_start_at.isoformat(timespec="seconds")
+
+        # Pre-probe (hot-path discipline + [Dedup mustn't gate side effects]):
+        # which configured thresholds are STILL un-recorded for this week?
+        # The cost SUM is skipped ONLY when every threshold already has a row
+        # — so a partial prior run that recorded some-but-not-all thresholds
+        # still gets the remaining ones a SUM + crossing-check. The skip never
+        # owes a crossing: an un-recorded threshold always forces the SUM.
+        present = {
+            int(r[0]) for r in conn.execute(
+                "SELECT threshold FROM budget_milestones WHERE week_start_at = ?",
+                (week_key,),
+            )
+        }
+        pending = [t for t in sorted(thresholds) if t not in present]
+        if not pending:
+            return  # nothing left to cross this week → skip the cost SUM
+
+        spent = _sum_cost_for_range(week_start_at, now_utc, mode="auto")
+        # target > 0 is guaranteed by _get_budget_config (weekly_usd None is
+        # excluded by _budget_alerts_active above); the else is belt-and-suspenders.
+        consumption_pct = (spent / target * 100.0) if target > 0 else 0.0
+        for t in pending:
+            # +1e-9 snap-up: spent/target*100 can land one ULP below an
+            # integer threshold (CLAUDE.md float-floor gotcha).
+            if consumption_pct + 1e-9 >= t:
+                inserted = insert_budget_milestone(
+                    conn,
+                    week_start_at=week_key,
+                    threshold=t,
+                    budget_usd=target,
+                    spent_usd=spent,
+                    consumption_pct=consumption_pct,
+                    commit=False,
+                )
+                # Only the genuine-new-crossing winner (rowcount==1) dispatches;
+                # a racing record-usage instance gets rowcount==0 and skips.
+                if inserted == 1:
+                    crossed_at = now_utc_iso()
+                    # set-then-dispatch: alerted_at lands on the row BEFORE
+                    # the osascript Popen, sharing this transaction with the
+                    # INSERT (commit=False) so a crash between them is
+                    # impossible. `alerted_at IS NULL` guard is write-once
+                    # defense-in-depth.
+                    conn.execute(
+                        "UPDATE budget_milestones SET alerted_at = ? "
+                        "WHERE week_start_at = ? AND threshold = ? "
+                        "  AND alerted_at IS NULL",
+                        (crossed_at, week_key, t),
+                    )
+                    pending_alerts.append(_build_alert_payload_budget(
+                        threshold=t,
+                        crossed_at_utc=crossed_at,
+                        week_start_at=week_key,
+                        budget_usd=target,
+                        spent_usd=spent,
+                        consumption_pct=consumption_pct,
+                    ))
+        # Single commit: every INSERT + its alerted_at marker durable together.
+        conn.commit()
+    except Exception as exc:
+        eprint(f"[budget-milestone] error recording budget milestone: {exc}")
+    finally:
+        conn.close()
+
+    # Dispatch AFTER commit; a dispatch failure NEVER rolls back the milestone
+    # (set-then-dispatch invariant — one queue attempt per crossing, deduped
+    # on the alerted_at column).
+    for payload in pending_alerts:
+        try:
+            _dispatch_alert_notification(payload, mode="real")
+        except Exception as dispatch_exc:
+            eprint(f"[budget-alerts] dispatch failed: {dispatch_exc}")
+
+
 def _compute_block_totals(
     block_start_at: dt.datetime,
     range_end: dt.datetime,
@@ -2178,6 +2319,13 @@ def cmd_record_usage(args: argparse.Namespace) -> int:
     except Exception as exc:
         eprint(f"[5h-block] unexpected error: {exc}")
 
+    # NEW: equiv-$ budget alert firing (Approach A, issue #19). Gated on a
+    # set budget + alerts_enabled FIRST — non-budget users pay zero overhead.
+    try:
+        maybe_record_budget_milestone(saved)
+    except Exception as exc:
+        eprint(f"[budget-milestone] unexpected error: {exc}")
+
     # Write high-water mark so the status line never displays a regression.
     # The file contains "week_start_date weekly_percent" on one line.
     try: