cctally 1.22.4 → 1.24.0

package/bin/_cctally_core.py

@@ -427,7 +427,18 @@ class _AlertsConfigError(ValueError):
     """Raised by _get_alerts_config on invalid alerts block."""
 
 
-_ALERTS_CONFIG_VALID_KEYS = {"enabled", "weekly_thresholds", "five_hour_thresholds"}
+_ALERTS_CONFIG_VALID_KEYS = {
+    "enabled",
+    "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]":
@@ -499,10 +510,56 @@ def _get_alerts_config(cfg: "dict | None") -> dict:
     five_hour = _validate_threshold_list(
         "five_hour_thresholds", block.get("five_hour_thresholds", [90, 95])
     )
+    # projected-pace opt-in (#121); default OFF so upgrades fire no surprise
+    # notifications. Bool-validated (NOT coerced) so a non-bool is a config
+    # error, not silently truthy.
+    projected_enabled = block.get("projected_enabled", False)
+    if not isinstance(projected_enabled, bool):
+        raise _AlertsConfigError(
+            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,
     }
 
 
@@ -517,8 +574,14 @@ _BUDGET_DEFAULTS = {
     "weekly_usd": None,            # None = no budget (default)
     "alerts_enabled": True,        # "on when set"
     "alert_thresholds": [90, 100],
+    "projected_enabled": False,    # projected-pace opt-in (#121); default OFF
+}
+_BUDGET_CONFIG_VALID_KEYS = {
+    "weekly_usd",
+    "alerts_enabled",
+    "alert_thresholds",
+    "projected_enabled",
 }
-_BUDGET_CONFIG_VALID_KEYS = {"weekly_usd", "alerts_enabled", "alert_thresholds"}
 
 
 def _get_budget_config(cfg: dict) -> dict:
@@ -579,6 +642,12 @@ def _get_budget_config(cfg: dict) -> dict:
             cleaned.append(t)
         out["alert_thresholds"] = sorted(set(cleaned))  # empty list allowed (silenced)
 
+    if "projected_enabled" in block:
+        v = block["projected_enabled"]
+        if not isinstance(v, bool):
+            raise _BudgetConfigError("budget.projected_enabled must be a boolean")
+        out["projected_enabled"] = v
+
     return out
 
 
@@ -1027,6 +1096,37 @@ def open_db() -> sqlite3.Connection:
         """
     )
 
+    # ── projected_milestones (week-average-pace projection crossings — #121) ──
+    # Plain CREATE TABLE IF NOT EXISTS, NO migration handler / backfill — same
+    # posture as `budget_milestones` (write-once, forward-only, no
+    # `reset_event_id` segment column). Two metrics share the table, keyed by
+    # `metric` ('weekly_pct' | 'budget_usd'); a level fires once the
+    # WEEK-AVERAGE projection (not the displayed high-end verdict) crosses
+    # `threshold`. `denominator` snapshots the target AT crossing (target_usd
+    # for budget_usd, 100.0 for weekly_pct) so the dashboard envelope renders
+    # context "$312 of $300" / "102% of cap" from the ROW, not from live config
+    # that may have changed since (Codex P0-4). A mid-week reset re-anchors
+    # `week_start_at` (new window → fresh rows under the UNIQUE key), the
+    # budget-pattern reset handling — hence NO `reset_event_id` column.
+    # `alerted_at` is stamped BEFORE the osascript Popen (set-then-dispatch).
+    # Lives BEFORE the migration dispatcher: a plain CREATE on a
+    # framework-untracked table never touches `schema_migrations`.
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS projected_milestones (
+            id              INTEGER PRIMARY KEY AUTOINCREMENT,
+            week_start_at   TEXT    NOT NULL,
+            metric          TEXT    NOT NULL,   -- 'weekly_pct' | 'budget_usd'
+            threshold       INTEGER NOT NULL,   -- 90 | 100
+            projected_value REAL    NOT NULL,
+            denominator     REAL    NOT NULL,   -- target_usd (budget) | 100.0 (weekly)
+            crossed_at_utc  TEXT    NOT NULL,
+            alerted_at      TEXT,
+            UNIQUE(week_start_at, metric, 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