cctally 1.23.0 → 1.25.0

package/bin/_cctally_core.py

@@ -432,8 +432,14 @@ _ALERTS_CONFIG_VALID_KEYS = {
     "weekly_thresholds",
     "five_hour_thresholds",
     "projected_enabled",
+    "notifier",
+    "command_template",
 }
 
+# Dispatch backends (Phase B). "auto" picks a platform default; "command"
+# routes through alerts.command_template (which it then requires).
+_ALERTS_VALID_NOTIFIERS = ("auto", "osascript", "notify-send", "command", "none")
+
 
 def _validate_threshold_list(name: str, value: object) -> "list[int]":
     """Validate one of the alerts threshold lists.
@@ -513,11 +519,47 @@ def _get_alerts_config(cfg: "dict | None") -> dict:
             f"alerts.projected_enabled must be a JSON boolean, got "
             f"{type(projected_enabled).__name__}: {projected_enabled!r}"
         )
+    # Dispatch-global keys (Phase B). `notifier` selects the backend;
+    # `command_template` is an argv list for the `command` backend (and may be
+    # set ahead of switching the backend). The cross-field constraint
+    # (notifier='command' requires a template) is enforced last.
+    notifier = block.get("notifier", "auto")
+    if notifier not in _ALERTS_VALID_NOTIFIERS:
+        raise _AlertsConfigError(
+            f"alerts.notifier must be one of {list(_ALERTS_VALID_NOTIFIERS)}, "
+            f"got {notifier!r}"
+        )
+    command_template = block.get("command_template", None)
+    if command_template is not None:
+        if not isinstance(command_template, list) or not command_template:
+            raise _AlertsConfigError(
+                "alerts.command_template must be null or a non-empty list of strings"
+            )
+        for el in command_template:
+            if not isinstance(el, str):
+                raise _AlertsConfigError(
+                    f"alerts.command_template elements must be strings, "
+                    f"got {type(el).__name__}: {el!r}"
+                )
+            if "\x00" in el:
+                raise _AlertsConfigError(
+                    "alerts.command_template elements must not contain a NUL byte"
+                )
+        if not command_template[0].strip():
+            raise _AlertsConfigError(
+                "alerts.command_template[0] (the program) must not be empty/whitespace"
+            )
+    if notifier == "command" and command_template is None:
+        raise _AlertsConfigError(
+            "alerts.notifier='command' requires alerts.command_template to be set"
+        )
     return {
         "enabled": enabled,
         "weekly_thresholds": weekly,
         "five_hour_thresholds": five_hour,
         "projected_enabled": projected_enabled,
+        "notifier": notifier,
+        "command_template": command_template,
     }
 
 
@@ -533,12 +575,16 @@ _BUDGET_DEFAULTS = {
     "alerts_enabled": True,        # "on when set"
     "alert_thresholds": [90, 100],
     "projected_enabled": False,    # projected-pace opt-in (#121); default OFF
+    "projects": {},               # per-project weekly $ budgets, keyed by git-root
+    "project_alerts_enabled": False,  # per-project alerts opt-in (#19/#121); default OFF
 }
 _BUDGET_CONFIG_VALID_KEYS = {
     "weekly_usd",
     "alerts_enabled",
     "alert_thresholds",
     "projected_enabled",
+    "projects",
+    "project_alerts_enabled",
 }
 
 
@@ -551,6 +597,7 @@ def _get_budget_config(cfg: dict) -> dict:
     """
     out = dict(_BUDGET_DEFAULTS)
     out["alert_thresholds"] = list(_BUDGET_DEFAULTS["alert_thresholds"])
+    out["projects"] = dict(_BUDGET_DEFAULTS["projects"])
     block = cfg.get("budget") if isinstance(cfg, dict) else None
     if block is None:
         return out
@@ -606,6 +653,41 @@ def _get_budget_config(cfg: dict) -> dict:
             raise _BudgetConfigError("budget.projected_enabled must be a boolean")
         out["projected_enabled"] = v
 
+    if "projects" in block:
+        v = block["projects"]
+        if not isinstance(v, dict):
+            raise _BudgetConfigError(
+                f"budget.projects must be an object, got {type(v).__name__}"
+            )
+        cleaned: "dict[str, float]" = {}
+        for proj_key, proj_val in v.items():
+            if not isinstance(proj_key, str):
+                raise _BudgetConfigError(
+                    "budget.projects keys must be strings (canonical git-root paths)"
+                )
+            # Reuse the weekly_usd numeric rule per value: a non-bool finite
+            # number > 0 (bool is an int subclass, so reject it explicitly).
+            if isinstance(proj_val, bool) or not isinstance(proj_val, (int, float)):
+                raise _BudgetConfigError(
+                    f"budget.projects values must be numbers, "
+                    f"got {type(proj_val).__name__} for key {proj_key!r}"
+                )
+            if not math.isfinite(float(proj_val)) or float(proj_val) <= 0:
+                raise _BudgetConfigError(
+                    f"budget.projects values must be finite numbers > 0, "
+                    f"got {proj_val!r} for key {proj_key!r}"
+                )
+            cleaned[proj_key] = float(proj_val)
+        out["projects"] = cleaned
+
+    if "project_alerts_enabled" in block:
+        v = block["project_alerts_enabled"]
+        if not isinstance(v, bool):
+            raise _BudgetConfigError(
+                "budget.project_alerts_enabled must be a boolean"
+            )
+        out["project_alerts_enabled"] = v
+
     return out
 
 
@@ -1085,6 +1167,42 @@ def open_db() -> sqlite3.Connection:
         """
     )
 
+    # ── project_budget_milestones (per-project equiv-$ budget crossings) ──────
+    # Plain CREATE TABLE IF NOT EXISTS, NO migration handler / backfill — the
+    # same posture as `budget_milestones` / `projected_milestones` (write-once,
+    # forward-only, framework-untracked). `project_key` is the NEW dimension in
+    # the UNIQUE key: each project crosses each threshold once per week,
+    # independently of every other project (issue #19 / #121, spec §5.1). It
+    # stores the canonical git-root (`ProjectKey.bucket_path`), matched by string
+    # equality against each session entry's resolved git-root. `budget_usd`
+    # snapshots the project's target AT crossing time so the dashboard renders
+    # "$26 of $25" from the ROW, not from live config that may have changed since
+    # (the Codex P0-4 lesson, already baked into `budget_milestones` /
+    # `projected_milestones`). A mid-week quota reset re-anchors `week_start_at`
+    # (new window → fresh rows under the UNIQUE key) — budget-pattern reset
+    # handling, hence NO `reset_event_id` segment column. `alerted_at` is stamped
+    # BEFORE dispatch (set-then-dispatch invariant); NULL = "recorded without
+    # dispatch" (forward-only-from-set reconcile) OR "not yet dispatched", never
+    # "delivery failed". Lives BEFORE the migration dispatcher: a plain CREATE on
+    # a framework-untracked table never touches `schema_migrations`, so the
+    # dispatcher's fresh-install snapshot is unaffected.
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS project_budget_milestones (
+            id              INTEGER PRIMARY KEY AUTOINCREMENT,
+            week_start_at   TEXT    NOT NULL,
+            project_key     TEXT    NOT NULL,   -- canonical git-root (bucket_path)
+            threshold       INTEGER NOT NULL,
+            budget_usd      REAL    NOT NULL,   -- project's target snapshotted AT crossing
+            spent_usd       REAL    NOT NULL,
+            consumption_pct REAL    NOT NULL,
+            crossed_at_utc  TEXT    NOT NULL,
+            alerted_at      TEXT,
+            UNIQUE(week_start_at, project_key, threshold)
+        )
+        """
+    )
+
     # Migration framework dispatcher. Replaces the prior inline gate stack
     # (has_blocks + _migration_done) with the framework's _run_pending_-
     # migrations entry point. See spec §2.3, §5.2 + the migration handlers

package/bin/_cctally_dashboard.py

@@ -340,6 +340,12 @@ def _build_alert_payload_projected(*args, **kwargs):
     return sys.modules["cctally"]._build_alert_payload_projected(*args, **kwargs)
 
 
+def _build_alert_payload_project_budget(*args, **kwargs):
+    return sys.modules["cctally"]._build_alert_payload_project_budget(
+        *args, **kwargs
+    )
+
+
 def _dispatch_alert_notification(*args, **kwargs):
     return sys.modules["cctally"]._dispatch_alert_notification(*args, **kwargs)
 
@@ -4252,6 +4258,72 @@ def _envelope_rows_projected(conn, descriptor, limit, severity_for) -> list[dict
     return out
 
 
+def _envelope_rows_project_budget(conn, descriptor, limit, severity_for) -> list[dict]:
+    # Fifth axis (issue #19 / #121): PER-PROJECT equiv-$ budget threshold
+    # crossings. Like the global budget axis, project-budget alerts re-anchor
+    # ``week_start_at`` on a mid-week reset, so there is NO ``reset_event_id``
+    # segment — the new window gets fresh rows under
+    # ``UNIQUE(week_start_at, project_key, threshold)``. ``project_key`` is the
+    # canonical git-root (``ProjectKey.bucket_path``); the human-readable chip
+    # context carries the project BASENAME, resolved through the production
+    # ``_resolve_project_key`` (git-root mode) so a moved/deleted repo still
+    # renders its basename from the snapshotted path (no FS dependency on a
+    # live ``.git``). ``budget_usd`` / ``spent_usd`` / ``consumption_pct`` are
+    # rendered FROM THE ROW (snapshotted at crossing), never live config that
+    # may have changed since (Codex P0-4). The envelope id mirrors the dispatch
+    # payload's ``project_budget:<week_start_at>:<project_key>:<threshold>``
+    # shape (``_build_alert_payload_project_budget``).
+    rows = conn.execute(
+        f"""
+        SELECT week_start_at, project_key, threshold, budget_usd, spent_usd,
+               consumption_pct, crossed_at_utc, alerted_at
+        FROM {descriptor.milestone_table}
+        WHERE alerted_at IS NOT NULL
+        ORDER BY alerted_at DESC
+        LIMIT ?
+        """,
+        (limit,),
+    ).fetchall()
+    c = _cctally()
+    resolve = c._resolve_project_key
+    resolver_cache: dict = {}
+    # Collision-aware labels ACROSS the distinct project_keys in these rows so
+    # two same-basename roots (/work/app + /personal/app) don't both render
+    # "app" — byte-matching the live notification + budget table via the shared
+    # `_project_disambiguate_labels`. Disambiguated across the ROWS (not live
+    # config) to preserve the render-from-the-snapshotted-row invariant above.
+    distinct_keys = sorted({r["project_key"] for r in rows})
+    pkeys = [resolve(k, "git-root", resolver_cache) for k in distinct_keys]
+    disambig = c._project_disambiguate_labels([{"key": pk} for pk in pkeys])
+    label_by_key = {
+        distinct_keys[i]: disambig.get(i, pkeys[i].display_key)
+        for i in range(len(distinct_keys))
+    }
+    out: list[dict] = []
+    for r in rows:
+        threshold = int(r["threshold"])
+        project_key = r["project_key"]
+        out.append({
+            "id": (
+                f"project_budget:{r['week_start_at']}:{project_key}:{threshold}"
+            ),
+            "axis":       descriptor.id,
+            "threshold":  threshold,
+            "severity":   severity_for(threshold),
+            "crossed_at": r["crossed_at_utc"],
+            "alerted_at": r["alerted_at"],
+            "context": {
+                "week_start_at":   r["week_start_at"],
+                "project":         label_by_key.get(project_key, project_key),
+                "project_key":     project_key,
+                "budget_usd":      float(r["budget_usd"]),
+                "spent_usd":       float(r["spent_usd"]),
+                "consumption_pct": float(r["consumption_pct"]),
+            },
+        })
+    return out
+
+
 # Keyed by ``AlertAxisDescriptor.id`` — the registry decides which axes run,
 # in what order; this table supplies the bespoke heterogeneous row-mapper.
 _ENVELOPE_AXIS_MAPPERS = {
@@ -4259,6 +4331,7 @@ _ENVELOPE_AXIS_MAPPERS = {
     "five_hour": _envelope_rows_five_hour,
     "budget": _envelope_rows_budget,
     "projected": _envelope_rows_projected,
+    "project_budget": _envelope_rows_project_budget,
 }
 
 
@@ -4269,19 +4342,20 @@ def _build_alerts_envelope_array(
     """Return the ``alerts`` array for the SSE snapshot envelope.
 
     Union of ``percent_milestones``, ``five_hour_milestones``,
-    ``budget_milestones``, and ``projected_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).
-
-    All four axes share the same envelope schema; the ``axis`` field
-    (``weekly`` / ``five_hour`` / ``budget`` / ``projected``) discriminates.
-    The ``projected`` axis additionally carries a top-level ``metric``
-    (``weekly_pct`` | ``budget_usd``) so the frontend can pick its
-    metric-aware context renderer.
+    ``budget_milestones``, ``projected_milestones``, and
+    ``project_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).
+
+    All five axes share the same envelope schema; the ``axis`` field
+    (``weekly`` / ``five_hour`` / ``budget`` / ``projected`` /
+    ``project_budget``) discriminates. The ``projected`` axis additionally
+    carries a top-level ``metric`` (``weekly_pct`` | ``budget_usd``) so the
+    frontend can pick its metric-aware context renderer; ``project_budget``
+    carries the project basename + ``$spent of $budget`` in its context.
 
     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
@@ -4687,6 +4761,12 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
             "weekly_thresholds": [],
             "five_hour_thresholds": [],
             "projected_enabled": False,
+            # Mirror the dispatch keys so the new alerts_settings lines
+            # (`notifier` / `command_configured`) don't KeyError on a
+            # corrupt config. Safe defaults: no notifier override, no
+            # configured command.
+            "notifier": "auto",
+            "command_template": None,
         }
     # Budget is its OWN config block (issue #19) — source budget fields
     # from ``_get_budget_config`` (the validated ``budget`` block), NOT
@@ -4696,7 +4776,8 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         _budget_cfg = _get_budget_config(_cfg_for_alerts)
     except _BudgetConfigError:
         _budget_cfg = {"weekly_usd": None, "alerts_enabled": True,
-                       "alert_thresholds": [], "projected_enabled": False}
+                       "alert_thresholds": [], "projected_enabled": False,
+                       "projects": {}, "project_alerts_enabled": False}
     alerts_settings = {
         "enabled":              _alerts_cfg["enabled"],
         "weekly_thresholds":    list(_alerts_cfg["weekly_thresholds"]),
@@ -4708,6 +4789,21 @@ def snapshot_to_envelope(snap: "DataSnapshot", *,
         # from the validated getters' ``projected_enabled`` (default False).
         "projected_weekly_enabled": bool(_alerts_cfg.get("projected_enabled")),
         "projected_budget_enabled": bool(_budget_cfg.get("projected_enabled")),
+        # Per-project budget alerts opt-in mirror (issue #19 / #121). Gates the
+        # ``project_budget`` axis dispatch only (the display section always
+        # renders configured projects). Sourced from the validated budget
+        # getter's ``project_alerts_enabled`` (default False) — the frontend
+        # SettingsOverlay seeds a single on/off toggle from it.
+        "project_alerts_enabled": bool(_budget_cfg.get("project_alerts_enabled")),
+        # Alert-dispatch notifier mirror (Phase B). `notifier` is the
+        # validated backend selector ("auto"/"command"/etc.). The raw
+        # `command_template` is NEVER mirrored — it routinely holds secrets
+        # (webhook URLs, bearer tokens) and the SSE snapshot is broadcast to
+        # every connected client. We expose only a boolean: is a custom
+        # command configured? (the CLI/config remains the sole writer of the
+        # template itself).
+        "notifier":           _alerts_cfg.get("notifier", "auto"),
+        "command_configured": _alerts_cfg.get("command_template") is not None,
     }
 
     # Mirror update-state.json + update-suppress.json into the envelope
@@ -5347,7 +5443,12 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         sent) is the full computed block from ``_compute_display_block``
         (preserves ``tz`` / ``resolved_tz`` / ``offset_label`` /
         ``offset_seconds`` shape consumers rely on). ``alerts`` (when
-        sent) is the full validated block from ``_get_alerts_config``.
+        sent) is the full validated block from ``_get_alerts_config``,
+        except the raw ``command_template`` is redacted to the boolean
+        ``command_configured`` (it routinely holds secrets — webhook URLs
+        / bearer tokens — and the echo is returned to the client; the
+        SSE ``alerts_settings`` mirror redacts identically). Do NOT
+        re-add the raw template to the echo.
         ``saved_at`` is included for backward compat.
         """
         if not self._check_origin_csrf():
@@ -5487,6 +5588,27 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                     {"error": "alerts.projected_enabled must be a JSON boolean"},
                 )
                 return
+            # The dispatch command template is CLI/config-only — never
+            # settable via the dashboard (it routinely holds secrets and the
+            # dashboard echoes settings to the client). Reject it explicitly
+            # rather than silently dropping it.
+            if "command_template" in alerts_block:
+                self._respond_json(
+                    400,
+                    {"error": "alerts.command_template is CLI/config-only "
+                              "(not settable via the dashboard)"},
+                )
+                return
+            # `notifier` is settable (the backend selector). Structural type
+            # check only; the enum + cross-field rule (command needs a stored
+            # template) is enforced free by `_get_alerts_config(merged)` below.
+            if "notifier" in alerts_block and not isinstance(
+                alerts_block["notifier"], str
+            ):
+                self._respond_json(
+                    400, {"error": "alerts.notifier must be a string"}
+                )
+                return
 
         # Pre-validate budget shape (the structural type check; full
         # cross-key validation runs inside the lock via
@@ -5602,6 +5724,8 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                     merged_alerts["projected_enabled"] = (
                         alerts_in["projected_enabled"]
                     )
+                if "notifier" in alerts_in:
+                    merged_alerts["notifier"] = alerts_in["notifier"]
                 merged["alerts"] = merged_alerts
                 # Final cross-field validation against the merged block.
                 # _AlertsConfigError → 400 (no partial write since
@@ -5630,7 +5754,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 budget_in = payload["budget"]
                 for leaf in (
                     "weekly_usd", "alerts_enabled", "alert_thresholds",
-                    "projected_enabled",
+                    "projected_enabled", "project_alerts_enabled",
                 ):
                     if leaf in budget_in:
                         merged_budget[leaf] = budget_in[leaf]
@@ -5703,7 +5827,14 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 merged, dt.datetime.now(dt.timezone.utc)
             )
         if "alerts" in payload:
-            out["alerts"] = _get_alerts_config(merged)
+            # Echo the full validated alerts block (defaults filled) so the
+            # SettingsOverlay can repaint without a follow-up GET — but
+            # redact the raw `command_template` (secrets) the same way the
+            # SSE snapshot mirror does: replace it with a boolean
+            # `command_configured`.
+            _a = dict(_get_alerts_config(merged))
+            _a["command_configured"] = _a.pop("command_template", None) is not None
+            out["alerts"] = _a
         if "budget" in payload:
             # Echo the full validated budget block (defaults filled) so the
             # SettingsOverlay can repaint without a follow-up GET.
@@ -5716,7 +5847,23 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             # 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)
+            #
+            # Gate each axis on the touched leaves (parity with `config set`):
+            # running on an unrelated leaf would latch a currently-over-but-
+            # not-yet-dispatched threshold, permanently suppressing the next
+            # tick's dispatch. The dashboard accepts no `projects` leaf (the
+            # map is CLI-only), so the per-project axis keys on
+            # project_alerts_enabled/alert_thresholds.
+            budget_in = payload["budget"]
+            touched = (
+                set(budget_in.keys()) if isinstance(budget_in, dict) else set()
+            )
+            if touched & {"weekly_usd", "alerts_enabled", "alert_thresholds"}:
+                _cctally()._reconcile_budget_on_config_write(validated_budget)
+            if touched & {"project_alerts_enabled", "alert_thresholds"}:
+                _cctally()._reconcile_project_budget_milestones_on_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.
@@ -5768,11 +5915,13 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         dispatch status string in the JSON response.
 
         Body (all fields optional): ``{"axis":
-        "weekly"|"five_hour"|"budget"|"projected", "threshold": 1..100,
-        "metric": "weekly_pct"|"budget_usd"}``. Defaults: axis="weekly",
-        threshold=90, metric="weekly_pct". ``metric`` is only consulted for
-        the ``projected`` axis (mirrors the CLI ``alerts test --axis
-        projected --metric`` surface); it is ignored for the other axes.
+        "weekly"|"five_hour"|"budget"|"projected"|"project_budget",
+        "threshold": 1..100, "metric": "weekly_pct"|"budget_usd"}``. Defaults:
+        axis="weekly", threshold=90, metric="weekly_pct". ``metric`` is only
+        consulted for the ``projected`` axis (mirrors the CLI ``alerts test
+        --axis projected --metric`` surface); it is ignored for the other
+        axes. The ``project_budget`` axis dispatches a synthetic example
+        project ($26 of $25) — no real ``budget.projects`` entry required.
 
         IMPORTANT: ``axis`` uses the underscore form (``"five_hour"``)
         in the JSON API to match the dispatch payload's internal axis
@@ -5811,12 +5960,14 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 return
 
         axis = body.get("axis", "weekly")
-        if axis not in ("weekly", "five_hour", "budget", "projected"):
+        if axis not in (
+            "weekly", "five_hour", "budget", "projected", "project_budget",
+        ):
             self._respond_json(
                 400,
                 {"error": (
-                    "axis must be 'weekly', 'five_hour', 'budget' or "
-                    f"'projected', got {axis!r}"
+                    "axis must be 'weekly', 'five_hour', 'budget', "
+                    f"'projected' or 'project_budget', got {axis!r}"
                 )},
             )
             return
@@ -5867,6 +6018,22 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 spent_usd=300.0 * threshold / 100.0,
                 consumption_pct=float(threshold),
             )
+        elif axis == "project_budget":
+            # Synthetic per-project budget payload — mirrors the CLI
+            # ``alerts test --axis project_budget`` branch (NO DB writes,
+            # test/real divergence contract). Uses a fixed example project
+            # ($26 of $25 = 104%) so no real ``budget.projects`` entry is
+            # required; ``project_key`` is a placeholder canonical path.
+            payload = _build_alert_payload_project_budget(
+                threshold=threshold,
+                crossed_at_utc=now_utc_iso(),
+                week_start_at=dt.date.today().isoformat(),
+                project="example-project",
+                project_key="/example/repos/example-project",
+                budget_usd=25.0,
+                spent_usd=26.0,
+                consumption_pct=104.0,
+            )
         elif axis == "projected":
             # Synthetic projected-pace payload — mirrors the CLI
             # cmd_alerts_test projected branch (NO DB writes, test/real