cctally 1.7.0 → 1.7.1

package/CHANGELOG.md

@@ -5,6 +5,13 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.7.1] - 2026-05-15
+
+### Fixed
+- `cctally record-usage` / `sync-week`: `week_start_date` bucket key is now anchored on the canonical UTC calendar day of `week_start_at`, not the host-local-TZ `.date()` of the parsed datetime. When the cctally process briefly inherits a non-UTC `TZ` (e.g., `TZ=America/Los_Angeles` for a `+03:00` host process during refactor work), the same physical subscription week silently forks across two `week_start_date` values, leaving `cctally report` Trend with two rows per current window — one frozen at the moment of the TZ flip, one still updating. The writer fix at `_derive_week_from_payload` / `pick_week_selection` prevents new ghosts; a companion self-heal migration `004_heal_forked_week_start_date_buckets` merges any pre-existing forked rows on the next `open_db()` (usage/cost UPDATE the date columns to `substr(at, 1, 10)`; milestones DELETE on `UNIQUE(week_start_date, percent_threshold)` collision against the canonical row, else UPDATE). A new `data.forked_buckets` doctor check (visible in `cctally doctor` and the dashboard) surfaces the invariant as `fail` with per-table counts so the next regression is visible immediately. `_bootstrap_rename_legacy_markers` is now idempotent against the duplicate-marker case — both the legacy unprefixed and the new prefixed marker rows present from a back-and-forth across cctally versions — by DELETEing the legacy row when its prefixed counterpart already exists and preserving the prefixed row's authoritative `applied_at_utc`; previously the plain UPDATE collided on `schema_migrations.PRIMARY KEY` and permanently blocked the dispatcher from running any subsequent migration (including the heal).
+- `brew` installs: `cctally --help`, `cctally doctor`, the dashboard share GUI, and the CLI `--format md|html|svg` flag no longer crash with `FileNotFoundError` looking for runtime sibling modules. The Homebrew formula template's install block enumerated only `USER_FACING_BINS` since v1.4.0, so the lazy-loaded `_lib_doctor.py` / `_lib_share.py` / `_lib_share_templates.py` siblings never reached `libexec/bin` on brew layouts — `doctor`, the share modal, and the `--format` flag have been latently broken on every brew install since they landed. The v1.6.1 CHANGELOG note that "Homebrew copies the whole prefix; brew unaffected" was incorrect — the formula has always copied a per-name list, not the whole prefix. The bin/cctally split refactor on this branch promoted `_lib_semver` to an EAGER import at `bin/cctally:213`, which would have turned the latent crash into an immediate one (`cctally --help` itself stops resolving on a brew install missing the sibling). `homebrew/cctally.rb.template` now installs every `bin/_lib_*.py` and `bin/_cctally_*.py` runtime sibling via `Dir.glob` alongside `USER_FACING_BINS`, and `tests/test_package_files.py` gains a parity guard so future sibling additions can't silently drop out of the brew install layout. The next release cut after this branch merges ships a working brew formula for the first time since v1.4.0.
+- `update` (self-heal): `_self_heal_current_version` no longer corrupts the global `update-state.json` when `cctally` is invoked from a development clone. The post-command hook reads `CHANGELOG_PATH` via `__file__` (resolved against the dev tree's `CHANGELOG.md`, not the installed binary's), so any `./bin/cctally` invocation from the source tree — including the six phases of `cctally release` itself — stamped `current_version` to whatever the dev tree's CHANGELOG claimed, masking the actually-installed version on the user's machine until the next `rm ~/.local/share/cctally/update-state.json`. The self-heal now early-returns when a `.git/` directory sits next to `CHANGELOG_PATH`, since production tarballs (npm tar, brew archive) never ship `.git/`; legitimate out-of-band upgrades on installed npm/brew binaries still self-heal as before. Symmetric twin of the v1.7.0 brew fix (CHANGELOG-via-`__file__` ≠ installed-binary's CHANGELOG); same root cause, different trigger. Resolves [#42](https://github.com/omrikais/cctally-dev/issues/42).
+
 ## [1.7.0] - 2026-05-13
 
 ### Added

package/bin/_cctally_alerts.py

@@ -0,0 +1,231 @@
+"""Alert dispatch I/O + `cctally alerts test` entry point.
+
+Lazy I/O sibling: holds the two helpers that perform real-world side
+effects for the threshold-actions feature, plus the test-entry command:
+
+- `_alerts_log_path()` — resolve / mkdir the `alerts.log` path under
+  `LOG_DIR`. Pure path-derivation that touches the filesystem (creates
+  the parent dir) on every call.
+- `_dispatch_alert_notification(payload, *, popen_factory, mode, tz)` —
+  spawn `osascript` (best-effort, non-blocking) to display a macOS
+  Notification Center popup, then append a single tab-delimited line to
+  `alerts.log` with the terminal status. Fire-and-forget contract; never
+  raises.
+- `cmd_alerts_test(args)` — synthetic-payload entry point exposed via
+  `cctally alerts test`. Builds a payload through the same
+  `_build_alert_payload_*` helpers production uses, routes through
+  `_dispatch_alert_notification` with `mode="test"`, and reports the
+  outcome via stdout / exit code.
+
+The pure payload primitives (`_alert_text_weekly`,
+`_alert_text_five_hour`, `_escape_applescript_string`,
+`_build_alert_payload_weekly`, `_build_alert_payload_five_hour`) live
+in `bin/_lib_alerts_payload.py` (Phase A extraction); this module
+imports them directly via `_load_lib`, which keeps the dispatch path
+free of an extra bounce through cctally's re-exports.
+
+bin/cctally back-references via `_cctally()` (spec §5.5 pattern, same
+as `bin/_cctally_setup.py`):
+- `LOG_DIR` — base dir under which `alerts.log` lives (subject to
+  HOME-redirection by test fixtures via `monkeypatch.setitem(ns,
+  "LOG_DIR", ...)`).
+- `now_utc_iso` — single timestamp source used for both the log-line
+  timestamp and the synthetic test payload's `crossed_at_utc`.
+
+bin/cctally re-exports every public symbol below so the
+`bin/cctally-alerts-dispatch-test` harness (SourceFileLoader-based,
+attribute access via `m._dispatch_alert_notification(...)`) and the
+existing internal call sites in `cmd_record_usage` + the dashboard
+alerts/test handler resolve unchanged.
+
+Spec: docs/superpowers/specs/2026-05-13-bin-cctally-split-design.md
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import importlib.util as _ilu
+import os
+import pathlib
+import subprocess
+import sys
+
+
+def _cctally():
+    """Resolve the current `cctally` module at call-time (spec §5.5)."""
+    return sys.modules["cctally"]
+
+
+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
+
+
+_lib_alerts_payload = _load_lib("_lib_alerts_payload")
+_alert_text_weekly = _lib_alerts_payload._alert_text_weekly
+_alert_text_five_hour = _lib_alerts_payload._alert_text_five_hour
+_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
+
+
+def _alerts_log_path() -> "pathlib.Path":
+    """Return ``~/.local/share/cctally/logs/alerts.log`` (parent dirs created).
+
+    Resolves through the same ``APP_DIR`` / ``LOG_DIR`` derived at module
+    import time from ``Path.home()``, so a HOME override before import (the
+    pattern used elsewhere in this codebase — e.g. ``cctally-config-test``)
+    transparently relocates the log without a separate env-var convention.
+    """
+    log_dir = _cctally().LOG_DIR
+    log_dir.mkdir(parents=True, exist_ok=True)
+    return log_dir / "alerts.log"
+
+
+def _dispatch_alert_notification(
+    payload: dict,
+    *,
+    popen_factory=subprocess.Popen,
+    mode: str = "real",
+    tz: "object | None" = None,
+) -> str:
+    """Spawn osascript to display a macOS notification (non-blocking, best-effort).
+
+    Returns ``"queued"`` on successful Popen, ``"spawn_error: <ExcType>: <msg>"``
+    on failure. Writes EXACTLY ONE line to ``alerts.log`` with the terminal
+    status (no contradictory pre-/post-Popen log pair). Never raises:
+    Popen-spawn failures and log-write failures are both swallowed so the
+    dispatch contract stays independent of the OS / FS state.
+
+    Production callers ignore the return value (fire-and-forget); test
+    callers assert on it via an injected ``popen_factory``.
+
+    Integration-harness escape hatch: when ``popen_factory`` is left as
+    its default (``subprocess.Popen``) AND the env var
+    ``CCTALLY_TEST_POPEN_FACTORY=raise_filenotfound`` is set, swap in a
+    factory that raises ``FileNotFoundError("no osascript")``. Used by
+    ``bin/cctally-alerts-test`` to exercise the spawn-error branch
+    end-to-end (subprocess invocation of ``cctally record-usage`` —
+    direct kwargs-injection isn't reachable through the CLI). Only the
+    one canonical token is honored; unknown values fall through to real
+    Popen so a typo can't silently neuter dispatch in production.
+    """
+    if (
+        popen_factory is subprocess.Popen
+        and os.environ.get("CCTALLY_TEST_POPEN_FACTORY") == "raise_filenotfound"
+    ):
+        def _raise_filenotfound(*_args, **_kwargs):
+            raise FileNotFoundError("no osascript")
+        popen_factory = _raise_filenotfound
+
+    axis = payload["axis"]
+    if axis == "weekly":
+        title, subtitle, body = _alert_text_weekly(payload, tz)
+    elif axis == "five_hour":
+        title, subtitle, body = _alert_text_five_hour(payload, tz)
+    else:
+        title, subtitle, body = (
+            "cctally - alert",
+            "",
+            f"axis={axis} threshold={payload.get('threshold')}",
+        )
+
+    script = (
+        f'display notification "{_escape_applescript_string(body)}"'
+        f' with title "{_escape_applescript_string(title)}"'
+        f' subtitle "{_escape_applescript_string(subtitle)}"'
+    )
+
+    status: str
+    try:
+        popen_factory(
+            ["osascript", "-e", script],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            close_fds=True,
+            start_new_session=True,
+        )
+        status = "queued"
+    except (FileNotFoundError, PermissionError, OSError) as exc:
+        status = f"spawn_error: {exc.__class__.__name__}: {exc}"
+
+    # SINGLE log line per dispatch attempt (Codex P1#2 fix: no
+    # contradictory "queued" + "spawn_error" pair for the same call).
+    try:
+        log_path = _alerts_log_path()
+        ctx = payload.get("context") or {}
+        window_key = (
+            ctx.get("week_start_date")
+            or ctx.get("five_hour_window_key")
+            or ""
+        )
+        line = (
+            f"{_cctally().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:
+            f.write(line)
+    except OSError:
+        pass  # log-write failures must not affect dispatch contract
+
+    return status
+
+
+def cmd_alerts_test(args: argparse.Namespace) -> int:
+    """Send a synthetic test alert through the dispatch pipeline.
+
+    Builds a synthetic payload via the same ``_build_alert_payload_*``
+    helpers production uses, then routes through ``_dispatch_alert_notification``
+    with ``mode="test"`` so the alerts.log line carries the ``test``
+    discriminator (5th tab-delimited field) — distinguishes from real
+    threshold-crossing alerts written by ``cmd_record_usage``.
+
+    No DB writes: this path exists purely to validate end-to-end
+    osascript + log behavior. Exit codes:
+      0  alert was queued (Popen succeeded)
+      1  osascript missing on this host (FileNotFoundError)
+      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):
+        print(
+            f"cctally: --threshold must be in [1, 100], got {threshold}",
+            file=sys.stderr,
+        )
+        return 2
+    if axis == "weekly":
+        payload = _build_alert_payload_weekly(
+            threshold=threshold,
+            crossed_at_utc=c.now_utc_iso(),
+            week_start_date=dt.date.today().isoformat(),
+            cumulative_cost_usd=1.23,
+            dollars_per_percent=0.01,
+        )
+    else:
+        payload = _build_alert_payload_five_hour(
+            threshold=threshold,
+            crossed_at_utc=c.now_utc_iso(),
+            five_hour_window_key=int(dt.datetime.now(dt.timezone.utc).timestamp()),
+            block_start_at=c.now_utc_iso(),
+            block_cost_usd=1.23,
+            primary_model="claude-sonnet-4-6",
+        )
+    status = _dispatch_alert_notification(payload, mode="test")
+    if status == "queued":
+        print("Test alert dispatched (mode=test). Check Notification Center.")
+        return 0
+    if "FileNotFoundError" in status:
+        print(f"cctally: {status}", file=sys.stderr)
+        return 1
+    print(f"cctally: {status}", file=sys.stderr)
+    return 3