cctally 1.23.0 → 1.25.0

package/bin/_lib_alert_dispatch.py

@@ -0,0 +1,141 @@
+"""Pure kernel: cross-platform alert dispatch decisions + severity->urgency.
+
+resolve_notifier() picks the active notifier; build_command() returns the exact
+arg-list to spawn (osascript / notify-send / a config-driven command_template),
+or None ("no popup; log + dashboard only"). NO I/O at import time, and the
+decision is parameterized on `platform` + `which_on_path` so every OS branch is
+unit-testable from any host. bin/_cctally_alerts.py is the I/O glue: it injects
+the real sys.platform / shutil.which and spawns the result with shell=False.
+
+Trust model (spec Q3): alerts.command_template is *trusted local command
+execution* (the user owns config.json). shell=False + the arg-list form block
+alert-text shell-injection (a week label with $(...) or ; is one literal arg);
+the native notify-send path adds a `--` end-of-options delimiter against
+option-injection.
+
+Stdlib-only. bin/cctally re-exports the public symbols.
+Spec: docs/superpowers/specs/2026-06-02-alerts-dispatch-severity-seams-design.md
+"""
+from __future__ import annotations
+
+import importlib.util as _ilu
+import pathlib
+import sys
+
+# notify-send urgency tokens keyed by the 3-tier severity from
+# _lib_alert_axes.severity_for.
+_SEVERITY_URGENCY = {"info": "low", "warn": "normal", "critical": "critical"}
+
+# The documented command_template substitution tokens (one-pass, no re-scan).
+_TEMPLATE_TOKENS = frozenset(
+    {"title", "subtitle", "body", "severity", "urgency", "axis", "threshold", "metric"}
+)
+
+
+def _load_lib(name: str):
+    cached = sys.modules.get(name)
+    if cached is not None:
+        return cached
+    p = pathlib.Path(__file__).resolve().parent / f"{name}.py"
+    spec = _ilu.spec_from_file_location(name, p)
+    mod = _ilu.module_from_spec(spec)
+    sys.modules[name] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def severity_to_urgency(severity: str) -> str:
+    """Map a 3-tier severity to a notify-send urgency token."""
+    return _SEVERITY_URGENCY.get(severity, "normal")
+
+
+def resolve_notifier(cfg: dict, *, platform: str, which_on_path) -> str:
+    """Return the effective notifier id for this host + validated alerts cfg.
+
+    `platform` is a sys.platform-style string; `which_on_path` is a callable
+    name -> bool. An explicitly-selected native notifier that is unavailable on
+    this host downgrades to 'none' (rather than being spawned and failing).
+    """
+    selector = cfg.get("notifier", "auto")
+    template = cfg.get("command_template")
+    is_darwin = platform == "darwin"
+    is_linux = platform.startswith("linux")
+
+    if selector == "osascript":
+        return "osascript" if is_darwin else "none"
+    if selector == "notify-send":
+        return "notify-send" if (is_linux and which_on_path("notify-send")) else "none"
+    if selector == "command":
+        return "command" if template else "none"
+    if selector == "none":
+        return "none"
+    # auto
+    if template:
+        return "command"
+    if is_darwin:
+        return "osascript"
+    if is_linux and which_on_path("notify-send"):
+        return "notify-send"
+    return "none"
+
+
+def _substitute_tokens(arg: str, values: dict) -> str:
+    """One-pass left-to-right substitution: replace only the documented
+    {tokens}; leave every other character (including stray/unmatched braces)
+    literal; substituted values are NOT re-scanned. Missing keys -> ""."""
+    out = []
+    i, n = 0, len(arg)
+    while i < n:
+        ch = arg[i]
+        if ch == "{":
+            close = arg.find("}", i + 1)
+            if close != -1 and arg[i + 1:close] in _TEMPLATE_TOKENS:
+                out.append(str(values.get(arg[i + 1:close], "")))
+                i = close + 1
+                continue
+        out.append(ch)
+        i += 1
+    return "".join(out)
+
+
+def build_command(
+    notifier: str,
+    *,
+    title: str,
+    subtitle: str,
+    body: str,
+    severity: str,
+    urgency: str,
+    payload: dict,
+    command_template,
+):
+    """Return the arg-list to spawn for `notifier`, or None ('no popup')."""
+    if notifier == "osascript":
+        esc = _load_lib("_lib_alerts_payload")._escape_applescript_string
+        script = (
+            f'display notification "{esc(body)}"'
+            f' with title "{esc(title)}"'
+            f' subtitle "{esc(subtitle)}"'
+        )
+        return ["osascript", "-e", script]
+    if notifier == "notify-send":
+        folded = f"{subtitle}\n{body}" if subtitle.strip() else body
+        return ["notify-send", "-u", urgency, "--", title, folded]
+    if notifier == "command":
+        if not command_template:
+            return None
+        # A payload key present-but-None (e.g. a weekly payload's metric=None)
+        # substitutes as "" — same surface as an absent key.
+        def _pv(key):
+            v = payload.get(key)
+            return "" if v is None else v
+
+        values = {
+            "title": title, "subtitle": subtitle, "body": body,
+            "severity": severity, "urgency": urgency,
+            "axis": _pv("axis"),
+            "threshold": _pv("threshold"),
+            "metric": _pv("metric"),
+        }
+        return [_substitute_tokens(a, values) for a in command_template]
+    return None  # "none" or unknown -> no popup

package/bin/_lib_alerts_payload.py

@@ -244,6 +244,76 @@ def _build_alert_payload_budget(
     }
 
 
+def _alert_text_project_budget(
+    payload: dict, tz: "ZoneInfo | None"
+) -> tuple[str, str, str]:
+    """Build (title, subtitle, body) for a PER-PROJECT equiv-$ budget threshold
+    alert (axis ``project_budget``, spec §5.3).
+
+    Mirrors :func:`_alert_text_budget` but prefixed with the project's basename
+    so a user reading the notification knows WHICH project crossed (e.g.
+    *"Project foo - $26.00 of $25.00 (104% of budget)"*). The rendered numbers
+    come from the payload (snapshotted at crossing), never live config that may
+    have changed since (Codex P0-4). ``week_start_at`` is an instant but the
+    text doesn't render it, so no ``format_display_dt`` call is needed; ``tz`` is
+    accepted for signature parity with peer ``_alert_text_*`` builders and
+    intentionally unused (same as ``_alert_text_budget``).
+    """
+    threshold = int(payload["threshold"])
+    ctx = payload.get("context") or {}
+    project = ctx.get("project") or "(project)"
+    title = "cctally - project budget"
+    subtitle = f"{project} - {threshold}% of budget"
+    spent = float(ctx.get("spent_usd") or 0.0)
+    budget = float(ctx.get("budget_usd") or 0.0)
+    consumption = float(ctx.get("consumption_pct") or 0.0)
+    body = (
+        f"Project {project} - ${spent:,.2f} of ${budget:,.2f} "
+        f"({consumption:.0f}% of budget)"
+    )
+    return title, subtitle, body
+
+
+def _build_alert_payload_project_budget(
+    *,
+    threshold: int,
+    crossed_at_utc: str,
+    week_start_at: str,
+    project: str,
+    project_key: str,
+    budget_usd: float,
+    spent_usd: float,
+    consumption_pct: float,
+) -> dict:
+    """Build the alert payload for a PER-PROJECT equiv-$ budget threshold
+    crossing (axis ``project_budget``, the fifth alert axis; spec §5.3).
+
+    Mirrors :func:`_build_alert_payload_budget` with the project dimension
+    added: ``project`` is the collision-disambiguated basename
+    (``ProjectKey.display_key``, for human-readable notification text) and
+    ``project_key`` is the canonical git-root (``ProjectKey.bucket_path``, the
+    stable identity dimension of the UNIQUE dedup key). See
+    :func:`_build_alert_payload_weekly` for the ``alerted_at == crossed_at``
+    rationale (set-then-dispatch invariant). The dashboard envelope (Task 4)
+    surfaces this axis in the Recent-alerts panel from the row-sourced context.
+    """
+    return {
+        "id": f"project_budget:{week_start_at}:{project_key}:{int(threshold)}",
+        "axis": "project_budget",
+        "threshold": int(threshold),
+        "crossed_at": crossed_at_utc,
+        "alerted_at": crossed_at_utc,  # set-then-dispatch
+        "context": {
+            "week_start_at": week_start_at,
+            "project": project,
+            "project_key": project_key,
+            "budget_usd": float(budget_usd),
+            "spent_usd": float(spent_usd),
+            "consumption_pct": float(consumption_pct),
+        },
+    }
+
+
 def _alert_text_projected(payload: dict, tz: "ZoneInfo | None") -> tuple[str, str, str]:
     """Build (title, subtitle, body) for a projected-pace alert (#121).
 

package/bin/cctally

@@ -376,13 +376,20 @@ _lib_alerts_payload = _load_sibling("_lib_alerts_payload")
 _alert_text_weekly = _lib_alerts_payload._alert_text_weekly
 _alert_text_five_hour = _lib_alerts_payload._alert_text_five_hour
 _alert_text_budget = _lib_alerts_payload._alert_text_budget
+_alert_text_project_budget = _lib_alerts_payload._alert_text_project_budget
 _alert_text_projected = _lib_alerts_payload._alert_text_projected
 _escape_applescript_string = _lib_alerts_payload._escape_applescript_string
 _build_alert_payload_weekly = _lib_alerts_payload._build_alert_payload_weekly
 _build_alert_payload_five_hour = _lib_alerts_payload._build_alert_payload_five_hour
 _build_alert_payload_budget = _lib_alerts_payload._build_alert_payload_budget
+_build_alert_payload_project_budget = _lib_alerts_payload._build_alert_payload_project_budget
 _build_alert_payload_projected = _lib_alerts_payload._build_alert_payload_projected
 
+_lib_alert_dispatch = _load_sibling("_lib_alert_dispatch")
+resolve_notifier = _lib_alert_dispatch.resolve_notifier
+build_command = _lib_alert_dispatch.build_command
+severity_to_urgency = _lib_alert_dispatch.severity_to_urgency
+
 _lib_five_hour = _load_sibling("_lib_five_hour")
 _FIVE_HOUR_JITTER_FLOOR_SECONDS = _lib_five_hour._FIVE_HOUR_JITTER_FLOOR_SECONDS
 _floor_to_ten_minutes = _lib_five_hour._floor_to_ten_minutes
@@ -623,6 +630,10 @@ cmd_sync_week = _cctally_sync_week.cmd_sync_week
 # module-private (no external caller).
 _cctally_project = _load_sibling("_cctally_project")
 cmd_project = _cctally_project.cmd_project
+# Shared per-project cost compute (#19/#121, spec §7.1). Re-exported so the
+# per-project budget display (cmd_budget) and the Task 3 firing path reach it
+# via the cctally namespace.
+_sum_cost_by_project = _cctally_project._sum_cost_by_project
 
 # Eager re-export of bin/_cctally_pricing_check.py — `cmd_pricing_check`
 # is invoked via the parser's `set_defaults(func=c.cmd_pricing_check)`,
@@ -807,6 +818,7 @@ _PERCENT_NORMALIZE_DECIMALS = _cctally_record._PERCENT_NORMALIZE_DECIMALS
 _normalize_percent = _cctally_record._normalize_percent
 maybe_record_milestone = _cctally_record.maybe_record_milestone
 maybe_record_budget_milestone = _cctally_record.maybe_record_budget_milestone
+maybe_record_project_budget_milestone = _cctally_record.maybe_record_project_budget_milestone
 maybe_record_projected_alert = _cctally_record.maybe_record_projected_alert
 _weekly_pct_week_avg_projection = _cctally_record._weekly_pct_week_avg_projection
 _compute_block_totals = _cctally_record._compute_block_totals
@@ -1102,6 +1114,11 @@ _render_forecast_terminal = _cctally_forecast._render_forecast_terminal
 _BUDGET_JSON_SCHEMA_VERSION = _cctally_forecast._BUDGET_JSON_SCHEMA_VERSION
 _cmd_budget_set = _cctally_forecast._cmd_budget_set
 _cmd_budget_unset = _cctally_forecast._cmd_budget_unset
+# Per-project budget set/unset (#19/#121, spec §4.3 / §7).
+_resolve_project_budget_target = _cctally_forecast._resolve_project_budget_target
+_cmd_budget_set_project = _cctally_forecast._cmd_budget_set_project
+_cmd_budget_unset_project = _cctally_forecast._cmd_budget_unset_project
+_build_project_budget_rows = _cctally_forecast._build_project_budget_rows
 _budget_render_unset = _cctally_forecast._budget_render_unset
 _budget_verdict_ansi_code = _cctally_forecast._budget_verdict_ansi_code
 _budget_render_terminal = _cctally_forecast._budget_render_terminal
@@ -2063,10 +2080,12 @@ get_milestone_cost_for_week         = _cctally_milestones.get_milestone_cost_for
 get_milestones_for_week             = _cctally_milestones.get_milestones_for_week             # forecast c.; tui shim; percent-breakdown c.
 insert_percent_milestone            = _cctally_milestones.insert_percent_milestone            # record shim; idempotency-test mod.
 insert_budget_milestone             = _cctally_milestones.insert_budget_milestone             # record shim
+insert_project_budget_milestone     = _cctally_milestones.insert_project_budget_milestone     # record shim; project-budget-config-test ns[]
 insert_projected_milestone          = _cctally_milestones.insert_projected_milestone          # record shim
 _projected_levels_already_latched   = _cctally_milestones._projected_levels_already_latched   # record shim
 _reconcile_budget_milestones_on_set = _cctally_milestones._reconcile_budget_milestones_on_set # test_budget_alerts ns[]
 _reconcile_budget_on_config_write   = _cctally_milestones._reconcile_budget_on_config_write   # forecast/config/dashboard c.; test_forecast_ns_patch mod. patch
+_reconcile_project_budget_milestones_on_write = _cctally_milestones._reconcile_project_budget_milestones_on_write  # forecast/config/dashboard c. (forward-only project-budget reconcile)
 
 
 # === Update-banner predicate (spec §4.2) extracted to