cctally 1.22.2 → 1.22.4

package/bin/_cctally_milestones.py

@@ -0,0 +1,433 @@
+"""Weekly cost-snapshot persistence + percent/budget milestone DB layer.
+
+Eager I/O sibling: bin/cctally loads this at startup and re-exports all 11
+symbols onto the cctally namespace. Consumers reach them via the call-time
+``c = _cctally()`` accessor (forecast/config/dashboard/sync_week/view_models),
+``sys.modules["cctally"]`` shims (record/tui), and ``ns[...]`` in tests.
+
+Holds (11): WeekCostResult, compute_week_cost, get_latest_cost_for_week,
+insert_cost_snapshot, get_max_milestone_for_week, get_milestone_cost_for_week,
+get_milestones_for_week, insert_percent_milestone, insert_budget_milestone,
+_reconcile_budget_milestones_on_set, _reconcile_budget_on_config_write.
+
+Accessor discipline (spec §2): _cctally_core kernel symbols + _budget_alerts_active
+are honest-imported; _sum_cost_for_range / _resolve_current_budget_window are
+reached via the call-time _cctally() accessor (ns-patchable). No _lib_ kernel.
+"""
+from __future__ import annotations
+
+import datetime as dt
+import sqlite3
+import sys
+from dataclasses import dataclass
+
+from _cctally_core import (
+    _budget_alerts_active,
+    _canonicalize_optional_iso,
+    _command_as_of,
+    _get_latest_row_for_week,
+    eprint,
+    format_local_iso,
+    now_utc_iso,
+    open_db,
+    parse_iso_datetime,
+)
+
+
+def _cctally():
+    """Call-time accessor to the cctally module namespace (ns-patchable)."""
+    return sys.modules["cctally"]
+
+
+@dataclass
+class WeekCostResult:
+    week_start: dt.date
+    week_end: dt.date
+    start_iso: str
+    end_iso: str
+    cost_usd: float
+
+
+def compute_week_cost(
+    week_start: dt.date,
+    week_end: dt.date,
+    mode: str,
+    offline: bool,
+    project: str | None,
+    start_iso_override: str | None = None,
+    end_iso_override: str | None = None,
+) -> WeekCostResult:
+    # internal fallback: host-local intentional
+    now_local = dt.datetime.now().astimezone()
+    start_dt_override = (
+        parse_iso_datetime(start_iso_override, "weekStartAt")
+        if start_iso_override
+        else None
+    )
+    end_dt_override = (
+        parse_iso_datetime(end_iso_override, "weekEndAt")
+        if end_iso_override
+        else None
+    )
+    if start_dt_override is not None and end_dt_override is not None:
+        if end_dt_override <= start_dt_override:
+            raise ValueError("weekEndAt must be after weekStartAt")
+
+    if start_dt_override is not None:
+        start_iso = start_dt_override.isoformat(timespec="seconds")
+    else:
+        start_iso = format_local_iso(week_start, end_of_day=False)
+
+    if end_dt_override is not None:
+        in_current_window = (
+            start_dt_override is not None
+            and start_dt_override <= now_local < end_dt_override
+        )
+        end_iso = (
+            now_local.isoformat(timespec="seconds")
+            if in_current_window
+            else end_dt_override.isoformat(timespec="seconds")
+        )
+    else:
+        is_current_week = week_start <= now_local.date() <= week_end
+        end_iso = (
+            now_local.isoformat(timespec="seconds")
+            if is_current_week
+            else format_local_iso(week_end, end_of_day=True)
+        )
+
+    start_dt = parse_iso_datetime(start_iso, "start")
+    end_dt = parse_iso_datetime(end_iso, "end")
+
+    c = _cctally()
+    cost = c._sum_cost_for_range(start_dt, end_dt, mode=mode, project=project)
+
+    return WeekCostResult(
+        week_start=week_start,
+        week_end=week_end,
+        start_iso=start_iso,
+        end_iso=end_iso,
+        cost_usd=cost,
+    )
+
+
+def get_latest_cost_for_week(conn: sqlite3.Connection, week_ref: WeekRef) -> sqlite3.Row | None:
+    return _get_latest_row_for_week(conn, "weekly_cost_snapshots", week_ref)
+
+
+def insert_cost_snapshot(
+    conn: sqlite3.Connection,
+    week_start: dt.date,
+    week_end: dt.date,
+    week_start_at: str | None,
+    week_end_at: str | None,
+    range_start_iso: str,
+    range_end_iso: str,
+    cost_usd: float,
+    mode: str,
+    project: str | None,
+) -> int:
+    start_at = _canonicalize_optional_iso(week_start_at, "weekStartAt")
+    end_at = _canonicalize_optional_iso(week_end_at, "weekEndAt")
+    range_start = parse_iso_datetime(range_start_iso, "rangeStartIso").isoformat(timespec="seconds")
+    range_end = parse_iso_datetime(range_end_iso, "rangeEndIso").isoformat(timespec="seconds")
+    cur = conn.execute(
+        """
+        INSERT INTO weekly_cost_snapshots
+        (
+          captured_at_utc,
+          week_start_date,
+          week_end_date,
+          week_start_at,
+          week_end_at,
+          range_start_iso,
+          range_end_iso,
+          cost_usd,
+          mode,
+          project
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """,
+        (
+            now_utc_iso(),
+            week_start.isoformat(),
+            week_end.isoformat(),
+            start_at,
+            end_at,
+            range_start,
+            range_end,
+            cost_usd,
+            mode,
+            project,
+        ),
+    )
+    conn.commit()
+    return int(cur.lastrowid)
+
+
+def get_max_milestone_for_week(
+    conn: sqlite3.Connection,
+    week_start_date: str,
+    *,
+    reset_event_id: int = 0,
+) -> int | None:
+    """Return the highest percent_threshold recorded for a week's segment,
+    or None.
+
+    ``reset_event_id`` (v1.7.2): default 0 (= pre-credit / no-event
+    sentinel) preserves legacy behavior on un-credited weeks. When an
+    in-place credit lifts a week into a new segment, callers pass the
+    segment id so the segment's threshold ledger is independent of the
+    pre-credit one — the post-credit 1% / 2% / 3% milestones fire even
+    if the pre-credit segment already crossed those thresholds.
+    """
+    row = conn.execute(
+        """
+        SELECT MAX(percent_threshold) AS max_pct
+        FROM percent_milestones
+        WHERE week_start_date = ?
+          AND reset_event_id = ?
+        """,
+        (week_start_date, reset_event_id),
+    ).fetchone()
+    if row and row["max_pct"] is not None:
+        return int(row["max_pct"])
+    return None
+
+
+def get_milestone_cost_for_week(
+    conn: sqlite3.Connection,
+    week_start_date: str,
+    percent_threshold: int,
+    *,
+    reset_event_id: int = 0,
+) -> float | None:
+    """Return the cumulative_cost_usd for a specific (week, threshold,
+    segment), or None.
+
+    ``reset_event_id`` (v1.7.2): segment-aware lookup. Default 0 preserves
+    legacy behavior. Used by ``maybe_record_milestone`` to compute the
+    marginal cost between consecutive thresholds inside the SAME segment
+    — without the filter, the post-credit threshold-3 row would compute
+    its marginal against the pre-credit threshold-2 cost (wrong segment).
+    """
+    row = conn.execute(
+        """
+        SELECT cumulative_cost_usd
+        FROM percent_milestones
+        WHERE week_start_date = ?
+          AND percent_threshold = ?
+          AND reset_event_id = ?
+        """,
+        (week_start_date, percent_threshold, reset_event_id),
+    ).fetchone()
+    if row:
+        return float(row["cumulative_cost_usd"])
+    return None
+
+
+def get_milestones_for_week(
+    conn: sqlite3.Connection,
+    week_start_date: str,
+) -> list[sqlite3.Row]:
+    """Return all milestones for a week, ordered by threshold ascending."""
+    return conn.execute(
+        """
+        SELECT *
+        FROM percent_milestones
+        WHERE week_start_date = ?
+        ORDER BY percent_threshold ASC
+        """,
+        (week_start_date,),
+    ).fetchall()
+
+
+def insert_percent_milestone(
+    conn: sqlite3.Connection,
+    week_start_date: str,
+    week_end_date: str,
+    week_start_at: str | None,
+    week_end_at: str | None,
+    percent_threshold: int,
+    cumulative_cost_usd: float,
+    marginal_cost_usd: float | None,
+    usage_snapshot_id: int,
+    cost_snapshot_id: int,
+    five_hour_percent_at_crossing: float | None = None,
+    *,
+    commit: bool = True,
+    reset_event_id: int = 0,
+) -> int:
+    """Insert a percent_milestones row idempotently.
+
+    Returns the SQLite rowcount: 1 on a genuinely new crossing, 0 if a row
+    for (week_start_date, percent_threshold, reset_event_id) already exists.
+    Race-safe under concurrent record-usage instances — aligns with the
+    existing 5h-milestone INSERT OR IGNORE pattern (see five_hour_milestones
+    write path).
+
+    ``reset_event_id`` (v1.7.2 segment column, migration 005): defaults to
+    ``0`` (= pre-credit / no-event sentinel). When an in-place credit fires
+    for the current week, the caller (``maybe_record_milestone``) resolves
+    the active segment from ``week_reset_events`` and passes it in so
+    post-credit threshold crossings land as a SEPARATE row from any
+    pre-credit one at the same (week, threshold). The UNIQUE constraint
+    is on the 3-tuple, so (week=W, threshold=T, segment=0) and (W, T,
+    event_id) coexist.
+
+    Callers that need the row id MUST follow up with an explicit
+    `SELECT id FROM percent_milestones WHERE week_start_date=? AND
+    percent_threshold=? AND reset_event_id=?` query — `lastrowid` is
+    unreliable when the row is the silent-duplicate target.
+
+    ``commit=False`` skips the inner ``conn.commit()`` so the caller can
+    bundle the INSERT with a follow-up ``alerted_at`` UPDATE in a single
+    transaction (set-then-dispatch atomicity, spec §3.2). Used by
+    ``record_percent_milestone_if_crossed`` to mirror the 5h path's
+    single-commit pattern; without it, a crash between INSERT and UPDATE
+    permanently strands ``alerted_at`` NULL because the next call's
+    ``INSERT OR IGNORE`` returns rowcount==0 and the dispatch guard
+    ``if inserted == 1`` skips re-firing.
+    """
+    cur = conn.execute(
+        """
+        INSERT OR IGNORE INTO percent_milestones
+        (
+          captured_at_utc,
+          week_start_date,
+          week_end_date,
+          week_start_at,
+          week_end_at,
+          percent_threshold,
+          cumulative_cost_usd,
+          marginal_cost_usd,
+          usage_snapshot_id,
+          cost_snapshot_id,
+          five_hour_percent_at_crossing,
+          reset_event_id
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """,
+        (
+            now_utc_iso(),
+            week_start_date,
+            week_end_date,
+            week_start_at,
+            week_end_at,
+            percent_threshold,
+            cumulative_cost_usd,
+            marginal_cost_usd,
+            usage_snapshot_id,
+            cost_snapshot_id,
+            five_hour_percent_at_crossing,
+            reset_event_id,
+        ),
+    )
+    if commit:
+        conn.commit()
+    return int(cur.rowcount)
+
+
+def insert_budget_milestone(
+    conn: sqlite3.Connection,
+    *,
+    week_start_at: str,
+    threshold: int,
+    budget_usd: float,
+    spent_usd: float,
+    consumption_pct: float,
+    commit: bool = True,
+) -> int:
+    """INSERT OR IGNORE a budget threshold crossing. Returns ``cur.rowcount``
+    (1 = genuinely new crossing, 0 = INSERT OR IGNORE no-op on a pre-existing
+    ``(week_start_at, threshold)`` row).
+
+    Mirrors :func:`insert_percent_milestone`'s rowcount contract so the
+    alert-fire predicate (`if inserted == 1`) is race-safe without a
+    follow-up SELECT. ``alerted_at`` is left NULL — the caller stamps it in
+    the SAME transaction BEFORE dispatching (set-then-dispatch invariant,
+    CLAUDE.md Alerts gotcha). ``commit=False`` lets the caller bundle the
+    INSERT with the follow-up ``alerted_at`` UPDATE in one transaction so a
+    crash between them can't strand ``alerted_at`` NULL forever.
+    """
+    cur = conn.execute(
+        "INSERT OR IGNORE INTO budget_milestones "
+        "(week_start_at, threshold, budget_usd, spent_usd, consumption_pct, "
+        " crossed_at_utc) "
+        "VALUES (?, ?, ?, ?, ?, ?)",
+        (
+            week_start_at,
+            int(threshold),
+            float(budget_usd),
+            float(spent_usd),
+            float(consumption_pct),
+            now_utc_iso(),
+        ),
+    )
+    if commit:
+        conn.commit()
+    return int(cur.rowcount)
+
+
+def _reconcile_budget_milestones_on_set(conn, *, target, thresholds, now_utc):
+    """Forward-only-from-set reconcile (spec §5): on `budget set`, every
+    threshold ALREADY crossed for the current week is recorded with
+    ``alerted_at`` SET but WITHOUT dispatch — so setting a budget when you're
+    already at 95% does NOT instant-popup. Thresholds not yet crossed get NO
+    row, so they fire later via :func:`maybe_record_budget_milestone`.
+
+    A mid-week target change re-runs this; thresholds already alerted stay
+    deduped via UNIQUE(week_start_at, threshold) + the ``alerted_at IS NULL``
+    guard on the UPDATE (so an existing alerted row is never re-stamped).
+    """
+    c = _cctally()
+    window = c._resolve_current_budget_window(conn, now_utc)
+    if window is None:
+        return
+    week_start_at, _week_end_at = window
+    week_key = week_start_at.isoformat(timespec="seconds")
+    spent = c._sum_cost_for_range(week_start_at, now_utc, mode="auto")
+    # target > 0 guaranteed by the caller (_cmd_budget_set passes the validated
+    # weekly_usd); the else is belt-and-suspenders.
+    consumption_pct = (spent / target * 100.0) if target > 0 else 0.0
+    for t in sorted(thresholds):
+        if consumption_pct + 1e-9 >= t:
+            insert_budget_milestone(
+                conn,
+                week_start_at=week_key,
+                threshold=t,
+                budget_usd=target,
+                spent_usd=spent,
+                consumption_pct=consumption_pct,
+                commit=False,
+            )
+            conn.execute(
+                "UPDATE budget_milestones SET alerted_at = ? "
+                "WHERE week_start_at = ? AND threshold = ? AND alerted_at IS NULL",
+                (now_utc_iso(), week_key, t),
+            )
+    conn.commit()
+
+
+def _reconcile_budget_on_config_write(validated_budget):
+    """Forward-only reconcile shared by all three budget-config write
+    paths (`budget set`, `config set budget.*`, dashboard POST
+    /api/settings). Gated + best-effort: a budget with alerts off or no
+    thresholds records nothing; a stats.db failure never fails the write.
+    Runs OUTSIDE any config_writer_lock (open_db has its own locking)."""
+    thresholds = validated_budget.get("alert_thresholds") or []
+    if not (_budget_alerts_active(validated_budget) and thresholds):
+        return
+    try:
+        conn = open_db()
+        try:
+            _reconcile_budget_milestones_on_set(
+                conn,
+                target=validated_budget["weekly_usd"],
+                thresholds=thresholds,
+                now_utc=_command_as_of(),
+            )
+        finally:
+            conn.close()
+    except Exception as exc:  # best-effort; never fail the write
+        eprint(f"[budget-milestone] reconcile on set failed: {exc}")

package/bin/_cctally_percent_breakdown.py

@@ -0,0 +1,199 @@
+"""percent-breakdown command handler (cmd_percent_breakdown).
+
+Eager I/O sibling: bin/cctally loads this at startup and re-exports
+cmd_percent_breakdown onto the cctally namespace (parser dispatch in
+_cctally_parser.py: pb.set_defaults(func=c.cmd_percent_breakdown)).
+
+Accessor discipline (spec §2): _cctally_core kernel symbols are honest-imported;
+everything else — load_config, resolve_display_tz, _format_ts_compact,
+_boxed_table, _get_canonical_boundary_for_date, _apply_reset_events_to_weekrefs,
+get_milestones_for_week (a C2 symbol, reached on the ns) — via the call-time
+_cctally() accessor. No _lib_ kernel.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import sys
+
+from _cctally_core import (
+    _canonicalize_optional_iso,
+    compute_week_bounds,
+    get_week_start_name,
+    make_week_ref,
+    now_utc_iso,
+    open_db,
+    parse_date_str,
+)
+
+
+def _cctally():
+    """Call-time accessor to the cctally module namespace (ns-patchable)."""
+    return sys.modules["cctally"]
+
+
+def cmd_percent_breakdown(args: argparse.Namespace) -> int:
+    c = _cctally()
+    config = c.load_config()
+    tz = c.resolve_display_tz(args, config)
+    args._resolved_tz = tz
+    week_start_name = get_week_start_name(config, args.week_start_name)
+
+    conn = open_db()
+    try:
+        if args.week_start:
+            week_start = parse_date_str(args.week_start, "--week-start")
+        else:
+            latest_usage = conn.execute(
+                """
+                SELECT week_start_date
+                FROM weekly_usage_snapshots
+                ORDER BY captured_at_utc DESC, id DESC
+                LIMIT 1
+                """
+            ).fetchone()
+            if latest_usage is not None:
+                week_start = dt.date.fromisoformat(latest_usage["week_start_date"])
+            else:
+                # internal fallback: host-local intentional
+                now_local = dt.datetime.now().astimezone()
+                week_start, _ = compute_week_bounds(now_local, week_start_name)
+
+        week_start_date = week_start.isoformat()
+
+        # Get week_end from any snapshot for this week
+        end_row = conn.execute(
+            """
+            SELECT MAX(week_end_date) AS week_end_date
+            FROM (
+              SELECT week_end_date FROM weekly_usage_snapshots WHERE week_start_date = ?
+              UNION ALL
+              SELECT week_end_date FROM weekly_cost_snapshots WHERE week_start_date = ?
+              UNION ALL
+              SELECT week_end_date FROM percent_milestones WHERE week_start_date = ?
+            )
+            """,
+            (week_start_date, week_start_date, week_start_date),
+        ).fetchone()
+        week_end_date = end_row["week_end_date"] if end_row and end_row["week_end_date"] else (
+            (week_start + dt.timedelta(days=6)).isoformat()
+        )
+
+        # Apply reset-event boundary rewrites (same path get_recent_weeks
+        # uses) so the display header shows the effective window — e.g.
+        # a post-reset short week shows "2026-04-23..2026-04-25" rather
+        # than the backdated API-derived "2026-04-18..2026-04-25".
+        canon_start, canon_end = c._get_canonical_boundary_for_date(conn, week_start_date)
+        display_start_iso = canon_start
+        display_end_iso = canon_end
+        if canon_start and canon_end:
+            try:
+                base_ref = make_week_ref(
+                    week_start_date=week_start_date,
+                    week_end_date=week_end_date,
+                    week_start_at=canon_start,
+                    week_end_at=canon_end,
+                )
+                adjusted = c._apply_reset_events_to_weekrefs(conn, [base_ref])
+                if adjusted:
+                    display_start_iso = adjusted[0].week_start_at
+                    display_end_iso = adjusted[0].week_end_at
+            except ValueError:
+                pass
+
+        # v1.7.2 segment filter: when a week_reset_events row exists for
+        # the current ``week_end_at``, narrow the milestone listing to
+        # the active (latest) segment so a credited week's header (which
+        # already reflects the post-credit window via the canon-boundary
+        # rewrite above) is coherent with the body. Sentinel ``0`` covers
+        # pre-credit / no-event weeks; pre-005 DBs that didn't have the
+        # column also default to 0 via the migration's ALTER DEFAULT.
+        active_segment = 0
+        canon_end_for_lookup = None
+        latest_end_row = conn.execute(
+            "SELECT week_end_at FROM weekly_usage_snapshots "
+            "WHERE week_start_date = ? AND week_end_at IS NOT NULL "
+            "ORDER BY captured_at_utc DESC, id DESC LIMIT 1",
+            (week_start_date,),
+        ).fetchone()
+        if latest_end_row is not None:
+            canon_end_for_lookup = _canonicalize_optional_iso(
+                latest_end_row["week_end_at"], "pb.cur"
+            )
+        if canon_end_for_lookup:
+            seg_row = conn.execute(
+                "SELECT id FROM week_reset_events "
+                "WHERE new_week_end_at = ? "
+                "ORDER BY id DESC LIMIT 1",
+                (canon_end_for_lookup,),
+            ).fetchone()
+            if seg_row is not None:
+                active_segment = int(seg_row["id"])
+
+        milestones = [
+            m for m in c.get_milestones_for_week(conn, week_start_date)
+            if int(m["reset_event_id"] or 0) == active_segment
+        ]
+
+        milestone_list = []
+        for m in milestones:
+            milestone_list.append({
+                "percentThreshold": int(m["percent_threshold"]),
+                "cumulativeCostUSD": round(float(m["cumulative_cost_usd"]), 9),
+                "marginalCostUSD": round(float(m["marginal_cost_usd"]), 9) if m["marginal_cost_usd"] is not None else None,
+                "capturedAt": m["captured_at_utc"],
+                "fiveHourPercentAtCrossing": round(float(m["five_hour_percent_at_crossing"]), 1) if m["five_hour_percent_at_crossing"] is not None else None,
+            })
+
+        output = {
+            "weekStartDate": week_start_date,
+            "weekEndDate": week_end_date,
+            "weekStartAt": display_start_iso,
+            "weekEndAt": display_end_iso,
+            "milestones": milestone_list,
+            "generatedAt": now_utc_iso(),
+        }
+
+        if args.json:
+            print(json.dumps(output, indent=2))
+            return 0
+
+        # Prefer the reset-adjusted ISO timestamps in the terminal header
+        # when available; fall back to the raw dates for legacy installs.
+        if display_start_iso and display_end_iso:
+            print(
+                f"Week: {c._format_ts_compact(display_start_iso, tz=tz)} -> "
+                f"{c._format_ts_compact(display_end_iso, tz=tz)}"
+            )
+        else:
+            print(f"Week: {week_start_date}..{week_end_date}")
+        if not milestone_list:
+            if active_segment > 0:
+                # v1.7.2: distinguish post-credit empty (just got
+                # credited, no crossings yet) from genuinely-empty week.
+                # The pre-credit ledger still exists in the DB — just
+                # filtered out of the body — so the user shouldn't see
+                # "No milestones" and assume the data is gone.
+                print(
+                    "(post-credit segment, no milestones crossed yet)"
+                )
+            else:
+                print("No percent milestones recorded for this week.")
+            return 0
+
+        print("Percent breakdown:\n")
+        headers = ["#", "Threshold", "Cumulative Cost", "Marginal Cost", "5h at crossing"]
+        rows: list[list[str]] = []
+        for idx, m in enumerate(milestone_list, start=1):
+            pct = f"{m['percentThreshold']}%"
+            cum = f"${m['cumulativeCostUSD']:.6f}"
+            marg = f"${m['marginalCostUSD']:.6f}" if m["marginalCostUSD"] is not None else "n/a"
+            fh = f"{m['fiveHourPercentAtCrossing']:.0f}%" if m["fiveHourPercentAtCrossing"] is not None else "n/a"
+            rows.append([str(idx), pct, cum, marg, fh])
+
+        print(c._boxed_table(headers, rows, ["right", "right", "right", "right", "right"]))
+
+        return 0
+    finally:
+        conn.close()