cctally 1.11.0 → 1.12.0

package/bin/_cctally_config.py

@@ -9,25 +9,31 @@ predicate, `sync-week`, …) all resolve unchanged. Tests that mock
 work because Python's bare-name lookup inside non-extracted bin/cctally
 callers resolves in bin/cctally's namespace (where the re-export lives).
 
+What lives in bin/_cctally_core (promoted 2026-05-22, #84):
+  - ``CONFIG_PATH`` / ``CONFIG_LOCK_PATH`` path constants. Reads use
+    call-time ``_cctally_core.CONFIG_PATH`` / ``_cctally_core.CONFIG_LOCK_PATH``;
+    tests patch via ``monkeypatch.setattr(_cctally_core, "X", v)`` (or
+    the conftest ``redirect_paths()`` helper). The legacy
+    ``setitem(ns, "CONFIG_PATH", …)`` pattern is forbidden by
+    ``test_no_old_style_test_patches_for_promoted_globals``.
+
 What stays in bin/cctally:
   - ``_ALERTS_BAD_CONFIG_WARNED`` + ``_warn_alerts_bad_config_once`` —
     alerts-coupled warn-once flag/helper; the alerts-config readers
     (``_get_alerts_config`` / ``_AlertsConfigError``) still live in
     bin/cctally and these two travel with that block.
-  - ``CONFIG_PATH`` / ``CONFIG_LOCK_PATH`` path constants (spec §86–92
-    keeps every path constant in bin/cctally so monkeypatched
-    `cctally.CONFIG_PATH = …` redirects propagate everywhere).
   - ``eprint`` / ``ensure_dirs`` / ``DEFAULT_WEEK_START`` ubiquitous
     helpers/constants.
-  - All validator/normalizer primitives (``normalize_display_tz_value``,
-    ``_get_alerts_config``, ``_AlertsConfigError``,
-    ``_normalize_alerts_enabled_value``, ``_validate_dashboard_bind_value``,
+  - Non-path validator/normalizer primitives
+    (``_normalize_alerts_enabled_value``, ``_validate_dashboard_bind_value``,
     ``_normalize_update_check_enabled_value``,
     ``_validate_update_check_ttl_hours_value``,
     ``UPDATE_DEFAULT_TTL_HOURS``, ``get_display_tz_pref``) — these stay
     near the subsystem they belong to; we reach them via the
     ``_cctally()`` accessor (call-time lookup so test monkeypatches on
     bin/cctally's namespace still propagate, per spec §5.2).
+    (``normalize_display_tz_value`` imports directly from
+    ``_lib_display_tz`` — see the import block below.)
 
 Spec: docs/superpowers/specs/2026-05-13-bin-cctally-split-design.md
 """
@@ -49,14 +55,17 @@ def _cctally():
 
 
 # === Honest imports from extracted homes ===================================
-# Spec 2026-05-17-cctally-core-kernel-extraction.md §3.3: kernel symbols
-# import from _cctally_core; the Bucket-X helper `normalize_display_tz_value`
-# imports from `_lib_display_tz`. Path constants (`CONFIG_PATH`,
-# `CONFIG_LOCK_PATH`) plus out-of-scope validators
-# (`_normalize_alerts_enabled_value`, `_validate_dashboard_bind_value`,
-# `_validate_update_check_ttl_hours_value`, `_normalize_update_check_enabled_value`,
-# `get_display_tz_pref`, `UPDATE_DEFAULT_TTL_HOURS`) stay on the
-# _cctally() accessor.
+# Spec 2026-05-17 §3.3: kernel symbols import from _cctally_core; the
+# Bucket-X helper ``normalize_display_tz_value`` imports from
+# ``_lib_display_tz``. Path constants (``CONFIG_PATH``,
+# ``CONFIG_LOCK_PATH``) moved to _cctally_core 2026-05-22 (#84) and are
+# read via call-time ``_cctally_core.CONFIG_PATH`` etc. The out-of-scope
+# non-path validators (``_normalize_alerts_enabled_value``,
+# ``_validate_dashboard_bind_value``,
+# ``_validate_update_check_ttl_hours_value``,
+# ``_normalize_update_check_enabled_value``, ``get_display_tz_pref``,
+# ``UPDATE_DEFAULT_TTL_HOURS``) stay on the _cctally() accessor.
+import _cctally_core
 from _cctally_core import (
     eprint,
     ensure_dirs,
@@ -81,7 +90,7 @@ def _warn_config_corrupt_once(reason: str) -> None:
     _CONFIG_CORRUPT_WARNED = True
     c = _cctally()
     eprint(
-        f"warning: ignoring corrupt {c.CONFIG_PATH} ({reason}); "
+        f"warning: ignoring corrupt {_cctally_core.CONFIG_PATH} ({reason}); "
         "using in-memory defaults"
     )
 
@@ -106,10 +115,10 @@ def _try_read_config() -> "dict[str, Any] | None":
     config writer lock.
     """
     c = _cctally()
-    if not c.CONFIG_PATH.exists():
+    if not _cctally_core.CONFIG_PATH.exists():
         return None
     try:
-        raw = c.CONFIG_PATH.read_text(encoding="utf-8")
+        raw = _cctally_core.CONFIG_PATH.read_text(encoding="utf-8")
     except OSError as exc:
         _warn_config_corrupt_once(f"read failed: {exc}")
         return None
@@ -141,8 +150,8 @@ def config_writer_lock():
     """
     c = _cctally()
     ensure_dirs()
-    c.CONFIG_LOCK_PATH.touch()
-    fh = open(c.CONFIG_LOCK_PATH, "w")
+    _cctally_core.CONFIG_LOCK_PATH.touch()
+    fh = open(_cctally_core.CONFIG_LOCK_PATH, "w")
     try:
         fcntl.flock(fh, fcntl.LOCK_EX)
         try:
@@ -177,7 +186,7 @@ def load_config() -> dict[str, Any]:
     if parsed is not None:
         return parsed
 
-    if c.CONFIG_PATH.exists():
+    if _cctally_core.CONFIG_PATH.exists():
         # Corrupt file: warning already emitted by _try_read_config.
         # Return in-memory defaults; do NOT persist — a transient
         # corruption is recoverable by the next legitimate
@@ -227,14 +236,14 @@ def save_config(data: dict[str, Any]) -> None:
     c = _cctally()
     ensure_dirs()
     payload = (json.dumps(data, indent=2) + "\n").encode("utf-8")
-    tmp = c.CONFIG_PATH.with_name(f"{c.CONFIG_PATH.name}.tmp.{os.getpid()}")
+    tmp = _cctally_core.CONFIG_PATH.with_name(f"{_cctally_core.CONFIG_PATH.name}.tmp.{os.getpid()}")
     fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o644)
     try:
         os.write(fd, payload)
         os.fsync(fd)
     finally:
         os.close(fd)
-    os.replace(str(tmp), str(c.CONFIG_PATH))
+    os.replace(str(tmp), str(_cctally_core.CONFIG_PATH))
 
 
 ALLOWED_CONFIG_KEYS = (

package/bin/_cctally_core.py

@@ -5,14 +5,15 @@ logging (eprint), datetime helpers, week-name/bounds, time-of-day,
 alerts-config validation, open_db, WeekRef + make_week_ref,
 get_latest_usage_for_week.
 
-Path constants (APP_DIR, DB_PATH, LOG_DIR) intentionally live in
-bin/cctally and are read here via a call-time _cctally() accessor —
-this is the ONLY accessor use inside core. See
-docs/superpowers/specs/2026-05-17-cctally-core-kernel-extraction.md §2.
+Path constants (APP_DIR, DB_PATH, LOG_DIR, etc.) live in this module as
+of 2026-05-22 (issue #84); `_cctally_core` is the single source of truth
+and the only legal monkeypatch target for the 23 promoted globals listed
+below. See docs/superpowers/specs/2026-05-22-cctally-core-data-globals.md.
 """
 from __future__ import annotations
 import datetime as dt
 import os
+import pathlib
 import re
 import sqlite3
 import sys
@@ -25,6 +26,143 @@ def _cctally():
     return sys.modules["cctally"]
 
 
+# === Path constants ==================================================
+#
+# Promoted from bin/cctally per docs/superpowers/specs/2026-05-22-cctally-core-data-globals.md.
+# After this promotion `_cctally_core` is the single source of truth and
+# the only legal monkeypatch target. `bin/cctally` keeps eager re-exports
+# for ad-hoc REPL / scripts; tests MUST target this module directly.
+#
+# Path-constant initialization is wrapped in `_init_paths_from_env()` so
+# `tests/conftest.py:load_script()` can re-derive them from the current
+# HOME env var without re-importing this module (which would invalidate
+# tests' module-top `import _cctally_core` references). The bare module
+# attributes below are populated by the call to _init_paths_from_env()
+# at import time; subsequent load_script calls invoke it again.
+
+
+def _init_paths_from_env() -> None:
+    """(Re)bind the 23 in-scope path globals from the current process env.
+
+    22 of the 23 resolve under ``Path.home()`` (i.e. the ``HOME`` env var).
+    The 23rd, ``CHANGELOG_PATH``, resolves from ``CCTALLY_TEST_CHANGELOG_PATH``
+    when set, else from ``__file__`` (``<repo>/CHANGELOG.md`` relative to
+    this kernel module's location) — independent of ``HOME``. Tests that
+    redirect the changelog (e.g. ``tests/test_release_internals.py``) drive
+    that override and rely on this re-init.
+
+    Called once at module import to populate the defaults, then again
+    by `tests/conftest.py:load_script()` after each `setenv("HOME", …)`
+    or `setenv("CCTALLY_TEST_CHANGELOG_PATH", …)` so the test sees a fresh
+    path set without the cost of re-importing `_cctally_core` (which would
+    break tests that cached the module object via a top-level
+    `import _cctally_core`).
+    """
+    global APP_DIR, LEGACY_APP_DIR, LOG_DIR
+    global DB_PATH, CACHE_DB_PATH
+    global CACHE_LOCK_PATH, CACHE_LOCK_CODEX_PATH, CONFIG_LOCK_PATH
+    global CONFIG_PATH, MIGRATION_ERROR_LOG_PATH, CHANGELOG_PATH
+    global HOOK_TICK_LOG_DIR, HOOK_TICK_LOG_PATH, HOOK_TICK_LOG_ROTATED_PATH
+    global HOOK_TICK_THROTTLE_PATH, HOOK_TICK_THROTTLE_LOCK_PATH
+    global UPDATE_STATE_PATH, UPDATE_SUPPRESS_PATH
+    global UPDATE_LOCK_PATH, UPDATE_LOG_PATH, UPDATE_LOG_ROTATED_PATH
+    global UPDATE_CHECK_LAST_FETCH_PATH, CLAUDE_SETTINGS_PATH
+    global CLAUDE_PROJECTS_DIR
+
+    home = pathlib.Path.home()
+    APP_DIR = home / ".local" / "share" / "cctally"
+    LEGACY_APP_DIR = home / ".local" / "share" / "ccusage-subscription"
+    LOG_DIR = APP_DIR / "logs"
+
+    DB_PATH = APP_DIR / "stats.db"
+    CACHE_DB_PATH = APP_DIR / "cache.db"
+
+    CACHE_LOCK_PATH = APP_DIR / "cache.db.lock"
+    CACHE_LOCK_CODEX_PATH = APP_DIR / "cache.db.codex.lock"
+    CONFIG_LOCK_PATH = APP_DIR / "config.json.lock"
+
+    CONFIG_PATH = APP_DIR / "config.json"
+
+    MIGRATION_ERROR_LOG_PATH = LOG_DIR / "migration-errors.log"
+
+    # CHANGELOG_PATH: honor CCTALLY_TEST_CHANGELOG_PATH env override; otherwise
+    # resolves to <repo>/CHANGELOG.md based on bin/_cctally_core.py's
+    # location (alongside bin/cctally, so the parent chain is the same).
+    override = os.environ.get("CCTALLY_TEST_CHANGELOG_PATH")
+    if override:
+        CHANGELOG_PATH = pathlib.Path(override)
+    else:
+        CHANGELOG_PATH = pathlib.Path(__file__).resolve().parent.parent / "CHANGELOG.md"
+
+    HOOK_TICK_LOG_DIR = APP_DIR / "logs"
+    HOOK_TICK_LOG_PATH = HOOK_TICK_LOG_DIR / "hook-tick.log"
+    HOOK_TICK_LOG_ROTATED_PATH = HOOK_TICK_LOG_DIR / "hook-tick.log.1"
+    HOOK_TICK_THROTTLE_PATH = APP_DIR / "hook-tick.last-fetch"
+    HOOK_TICK_THROTTLE_LOCK_PATH = APP_DIR / "hook-tick.last-fetch.lock"
+
+    UPDATE_STATE_PATH = APP_DIR / "update-state.json"
+    UPDATE_SUPPRESS_PATH = APP_DIR / "update-suppress.json"
+    UPDATE_LOCK_PATH = APP_DIR / "update.lock"
+    UPDATE_LOG_PATH = APP_DIR / "update.log"
+    UPDATE_LOG_ROTATED_PATH = APP_DIR / "update.log.1"
+    UPDATE_CHECK_LAST_FETCH_PATH = APP_DIR / "update-check.last-fetch"
+
+    CLAUDE_SETTINGS_PATH = home / ".claude" / "settings.json"
+
+    # Claude session JSONL root. Production path is `~/.claude/projects`;
+    # exposed as a module-level constant so cross-DB migrations (e.g.
+    # stats migration 008) and the dispatcher's empty-disk fallback can
+    # honor a fixture override via tests' `monkeypatch.setattr(
+    # _cctally_core, "CLAUDE_PROJECTS_DIR", tmp_path / "...")`. The
+    # `_get_claude_data_dirs()` helper in bin/cctally remains the
+    # authoritative resolver for ad-hoc reads (multi-root + env-aware);
+    # this constant is the single-rooted production default that 99% of
+    # callers want. For multi-root, env-aware resolution (mirroring
+    # `_get_claude_data_dirs`), use `_resolve_claude_projects_dirs()`.
+    CLAUDE_PROJECTS_DIR = home / ".claude" / "projects"
+
+
+_init_paths_from_env()
+
+
+def _resolve_claude_projects_dirs() -> list[pathlib.Path]:
+    """Return Claude Code projects dirs that exist on disk, env-aware.
+
+    Mirrors `_get_claude_data_dirs()` in bin/cctally but returns the
+    `projects/` subdir directly (since cross-DB migrations only care
+    about the JSONL root, not the parent Claude data dir). Honors
+    ``CLAUDE_CONFIG_DIR`` (comma-separated multi-root) and falls back
+    to ``~/.config/claude`` then ``~/.claude``.
+
+    Used by stats migration 008's gate helper to avoid falsely
+    short-circuiting Layer C's empty-disk fallback when the user has
+    ``CLAUDE_CONFIG_DIR=/other/path`` set AND no ``~/.claude/projects``
+    dir on disk: the gate would otherwise see zero JSONL files at the
+    hardcoded ``CLAUDE_PROJECTS_DIR`` and "pass" the gate, then run the
+    recompute as a no-op against an empty cache.
+
+    Tests can also feed an explicit list to the gate helper directly,
+    skipping this resolver.
+    """
+    env_val = os.environ.get("CLAUDE_CONFIG_DIR", "").strip()
+    if env_val:
+        candidates = [pathlib.Path(p.strip()) for p in env_val.split(",") if p.strip()]
+        result = [
+            d / "projects"
+            for d in candidates
+            if d.is_dir() and (d / "projects").is_dir()
+        ]
+        if result:
+            return result
+
+    home = pathlib.Path.home()
+    defaults = [
+        home / ".config" / "claude",
+        home / ".claude",
+    ]
+    return [d / "projects" for d in defaults if d.is_dir() and (d / "projects").is_dir()]
+
+
 # === Logging =========================================================
 
 
@@ -240,9 +378,8 @@ def compute_week_bounds(anchor_dt: dt.datetime, week_start_name: str) -> tuple[d
 
 
 def ensure_dirs() -> None:
-    c = _cctally()
-    c.APP_DIR.mkdir(parents=True, exist_ok=True)
-    c.LOG_DIR.mkdir(parents=True, exist_ok=True)
+    APP_DIR.mkdir(parents=True, exist_ok=True)
+    LOG_DIR.mkdir(parents=True, exist_ok=True)
 
 
 # === Alerts validation cluster ======================================
@@ -353,7 +490,7 @@ def open_db() -> sqlite3.Connection:
     _clear_migration_error_log_entries = c._clear_migration_error_log_entries
 
     ensure_dirs()
-    conn = sqlite3.connect(c.DB_PATH)
+    conn = sqlite3.connect(DB_PATH)
     conn.row_factory = sqlite3.Row
     conn.execute("PRAGMA journal_mode=WAL")
     conn.execute("PRAGMA synchronous=NORMAL")

package/bin/_cctally_dashboard.py

@@ -256,6 +256,7 @@ def _cctally():
 # import from _cctally_core; already-decentralized buckets (X = _lib_*,
 # Y = _cctally_*) import from their natural home. These bypass the
 # legacy shim pattern entirely.
+import _cctally_core
 from _cctally_core import (
     eprint,
     now_utc_iso,
@@ -6548,7 +6549,7 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
                 c = _cctally()
                 conn.execute(
                     "ATTACH DATABASE ? AS cache_db",
-                    (str(c.CACHE_DB_PATH),),
+                    (str(_cctally_core.CACHE_DB_PATH),),
                 )
                 conn.execute(
                     "CREATE TEMP VIEW IF NOT EXISTS session_entries AS "