cctally 1.65.0 → 1.67.0

package/bin/_cctally_core.py

@@ -149,6 +149,20 @@ def _init_paths_from_env() -> None:
     CLAUDE_PROJECTS_DIR = home / ".claude" / "projects"
 
 
+def _truthy_env(name: str) -> bool:
+    """A ``1``/``true``/``yes``/any-other-non-empty env value is truthy;
+    unset, empty, ``0``, ``false``, ``no`` are falsey (case-insensitive,
+    whitespace-stripped).
+
+    Canonical home for boolean env-flag parsing (#279 S1 F1) — presence-only
+    ``os.environ.get(...)`` checks made ``FLAG=0`` mean *enabled*, which for
+    ``CCTALLY_ALLOW_PROD_MIGRATION`` / ``CCTALLY_DISABLE_DEV_AUTODETECT`` was
+    the exact opposite of intent. ``_cctally_telemetry._truthy_env`` delegates
+    here."""
+    v = os.environ.get(name)
+    return v is not None and v.strip().lower() not in ("", "0", "false", "no")
+
+
 def _repo_root() -> pathlib.Path:
     """Repo root when running from a source checkout: this file lives at
     ``<repo>/bin/_cctally_core.py``, so the root is two parents up. Factored
@@ -165,7 +179,7 @@ def _is_dev_checkout() -> bool:
     the ``setup`` guard (which protects WHICH BINARY gets wired into
     ~/.claude/settings.json), not the data-dir relocation. The npm/brew
     install copies ship without ``.git`` so they never read True."""
-    if os.environ.get("CCTALLY_DISABLE_DEV_AUTODETECT"):
+    if _truthy_env("CCTALLY_DISABLE_DEV_AUTODETECT"):
         return False
     return (_repo_root() / ".git").exists()
 
@@ -913,19 +927,40 @@ def open_db() -> sqlite3.Connection:
     ensure_dirs()
     conn = sqlite3.connect(DB_PATH)
     conn.row_factory = sqlite3.Row
-    conn.execute("PRAGMA journal_mode=WAL")
-    conn.execute("PRAGMA synchronous=NORMAL")
-    # Explicit for intent + symmetry with open_cache_db (bin/_cctally_cache.py).
-    # sqlite3.connect()'s default timeout=5.0 ALREADY maps to busy_timeout=5000,
-    # so this is not a behavior change — it makes the multi-writer retry window
-    # an explicit contract beside the WAL pragmas instead of an inherited
-    # default a reader has to know about. NOTE: busy_timeout does NOT absorb
-    # SQLITE_BUSY_SNAPSHOT (a WAL read-then-write transaction whose snapshot is
-    # invalidated by a competing commit raises "database is locked" instantly,
-    # bypassing the busy handler). The write paths defend against that by taking
-    # the write lock up front — BEGIN IMMEDIATE, or a write as the transaction's
-    # first DML. See cctally-dev#87.
-    conn.execute("PRAGMA busy_timeout=5000")
+    # #279 S1 F4: probe connect + initial PRAGMAs so a corrupt stats.db (the
+    # non-re-derivable DB) surfaces as a one-line diagnosis + exit 2 instead of
+    # a raw traceback. The catch boundary is DELIBERATELY narrow — ONLY the
+    # connect/PRAGMA/probe below. The DDL + `_run_pending_migrations` region
+    # further down is NOT wrapped: migration-handler failures have their own
+    # logging/suppression contract and must not be mislabeled as corruption
+    # (corruption that only surfaces mid-DDL stays a raw error; the probe
+    # catches the common case).
+    try:
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("PRAGMA synchronous=NORMAL")
+        # Explicit for intent + symmetry with open_cache_db (bin/_cctally_cache.py).
+        # sqlite3.connect()'s default timeout=5.0 ALREADY maps to busy_timeout=5000,
+        # so this is not a behavior change — it makes the multi-writer retry window
+        # an explicit contract beside the WAL pragmas instead of an inherited
+        # default a reader has to know about. NOTE: busy_timeout does NOT absorb
+        # SQLITE_BUSY_SNAPSHOT (a WAL read-then-write transaction whose snapshot is
+        # invalidated by a competing commit raises "database is locked" instantly,
+        # bypassing the busy handler). The write paths defend against that by taking
+        # the write lock up front — BEGIN IMMEDIATE, or a write as the transaction's
+        # first DML. See cctally-dev#87.
+        conn.execute("PRAGMA busy_timeout=5000")
+        conn.execute("SELECT 1").fetchone()
+    except sqlite3.DatabaseError as exc:
+        try:
+            conn.close()
+        except Exception:
+            pass
+        raise c.StatsDbCorruptError(
+            f"stats.db appears corrupt or unreadable ({exc}). path: {DB_PATH}. "
+            f"Not auto-recreated — it holds your recorded usage history. "
+            f'Recovery: back up the file, then try `sqlite3 "{DB_PATH}" ".recover"`, '
+            f"or move it aside to start fresh. If this recurs, please file an issue."
+        ) from exc
     conn.execute(
         """
         CREATE TABLE IF NOT EXISTS weekly_usage_snapshots (
@@ -1636,6 +1671,82 @@ def _reset_aware_floor(
     return row[0] if row and row[0] else None
 
 
+def _floored_week_max(conn, rows):
+    """Return {week_key -> per-week reset-aware-floored maximum weekly_percent}.
+
+    ``rows`` is an iterable of
+      (week_key, week_start_date, week_start_at, week_end_at,
+       captured_at_utc, weekly_percent).
+
+    Two-pass so floor resolution is independent of row order (#290): pass 1
+    buckets rows per ``week_key`` and canonicalizes each week's first non-NULL
+    (week_start_at, week_end_at) + its week_start_date; pass 2 resolves
+    ``_reset_aware_floor`` once per week (keyed on week_start_date) and drops
+    captures earlier than that floor before taking the week's maximum
+    ``weekly_percent``. ``week_key`` is the caller's aggregation key (1:1 with a
+    week); floor identity is week_start_date, so a NULL-bound legacy row cannot
+    suppress the reset-event leg for a later anchored row of the same week.
+
+    A NULL ``weekly_percent`` row is skipped. An unparseable ``captured_at_utc``
+    under an active floor is RETAINED (epoch unknown), matching
+    ``_cctally_project._load_week_snapshots``. All-NULL bounds resolve
+    credit-floor-leg-only (the reset leg is inert: unixepoch(NULL) is NULL).
+    A week whose every in-scope row is pre-floor is absent from the result.
+    """
+    # Pass 1: bucket + canonicalize bounds.
+    buckets: dict = {}
+    for wk, wsd, ws_at, we_at, cap, pct in rows:
+        if pct is None:
+            continue
+        b = buckets.get(wk)
+        if b is None:
+            buckets[wk] = {
+                "wsd": wsd, "ws_at": ws_at, "we_at": we_at,
+                "rows": [(cap, float(pct))],
+            }
+            continue
+        if b["wsd"] is None and wsd is not None:
+            b["wsd"] = wsd
+        if b["ws_at"] is None and ws_at is not None:
+            b["ws_at"] = ws_at
+        if b["we_at"] is None and we_at is not None:
+            b["we_at"] = we_at
+        b["rows"].append((cap, float(pct)))
+
+    # Pass 2: resolve floor once per week, drop pre-floor captures, take max.
+    result: dict = {}
+    for wk, b in buckets.items():
+        floor_iso = _reset_aware_floor(conn, b["wsd"], b["ws_at"], b["we_at"])
+        floor_epoch = None
+        if floor_iso:
+            try:
+                floor_epoch = int(
+                    parse_iso_datetime(
+                        floor_iso, "floored_week_max.floor"
+                    ).timestamp()
+                )
+            except ValueError:
+                floor_epoch = None
+        best = None
+        for cap, pct in b["rows"]:
+            if floor_epoch is not None and cap is not None:
+                try:
+                    cap_epoch = int(
+                        parse_iso_datetime(
+                            str(cap), "floored_week_max.cap"
+                        ).timestamp()
+                    )
+                except ValueError:
+                    cap_epoch = None
+                if cap_epoch is not None and cap_epoch < floor_epoch:
+                    continue
+            if best is None or pct > best:
+                best = pct
+        if best is not None:
+            result[wk] = best
+    return result
+
+
 def get_latest_usage_for_week(
     conn: sqlite3.Connection,
     week_ref: WeekRef,