cctally 1.17.0 → 1.19.0

package/bin/_lib_render.py

@@ -225,6 +225,124 @@ def _scale_down_col_widths(
 # Optional dependency: zoneinfo.ZoneInfo is referenced only as a string
 # annotation in moved code; no runtime import needed.
 
+
+def _render_title_banner(title: str, *, unicode_ok: bool, color: bool) -> str:
+    """ccusage-style rounded title banner (the box around a report title).
+
+    Returns the multi-line banner WITHOUT a trailing blank line; callers add
+    spacing. Shared by `_render_blocks_table` and `_render_active_block_box`.
+    """
+    def _bold(s: str) -> str:
+        return _style_ansi(s, "1", color)
+    title_padded = f"  {title}  "
+    tw = len(title_padded)
+    dash = "─" if unicode_ok else "-"
+    vb = "│" if unicode_ok else "|"
+    if unicode_ok:
+        top = f" ╭{dash * tw}╮"
+        bot = f" ╰{dash * tw}╯"
+    else:
+        top = f" +{'-' * tw}+"
+        bot = f" +{'-' * tw}+"
+    return "\n".join([
+        top,
+        f" {vb}" + " " * tw + vb,
+        f" {vb}" + _bold(title_padded) + vb,
+        f" {vb}" + " " * tw + vb,
+        bot,
+    ])
+
+
+def _fmt_block_time_local(ts: dt.datetime, tz: "ZoneInfo | None") -> str:
+    """Block-start timestamp in display tz, ccusage `toLocaleString`-style."""
+    local = ts.astimezone(tz)
+    hour_12 = local.hour % 12 or 12
+    ampm = "a.m." if local.hour < 12 else "p.m."
+    return (
+        f"{local.year}-{local.month:02d}-{local.day:02d}, "
+        f"{hour_12}:{local.minute:02d}:{local.second:02d} {ampm}"
+    )
+
+
+def _fmt_block_duration_hm(total_seconds: float) -> str:
+    total_minutes = int(total_seconds / 60)
+    return f"{total_minutes // 60}h {total_minutes % 60:02d}m"
+
+
+def _render_active_block_box(
+    block: "Block",
+    *,
+    now: dt.datetime,
+    tz: "ZoneInfo | None",
+    token_limit_explicit: int | None,
+    color: bool,
+    unicode_ok: bool,
+) -> str:
+    """ccusage `-a` 'Current Session Block Status' box (#86 Session F).
+
+    Token Limit Status sub-block appears only when `-t` was explicitly passed
+    (`token_limit_explicit` not None and > 0). Heuristic-anchored active blocks
+    get a `~`-prefixed start + approximate-start legend (Codex F2).
+    """
+    def _b(s: str) -> str:
+        return _style_ansi(s, "1", color)
+
+    lines: list[str] = [
+        _render_title_banner("Current Session Block Status",
+                             unicode_ok=unicode_ok, color=color),
+    ]
+    started = _fmt_block_time_local(block.start_time, tz)
+    approx = block.anchor == "heuristic"
+    if approx:
+        started = f"~{started}"
+    elapsed = max((now - block.start_time).total_seconds(), 0)
+    remaining = max((block.end_time - now).total_seconds(), 0)
+    lines.append(f"Block Started: {started} "
+                 f"({_fmt_block_duration_hm(elapsed)} ago)")
+    lines.append(f"Time Remaining: {_fmt_block_duration_hm(remaining)}")
+    if approx:
+        # Keep this wording in sync with the table footer legend below.
+        lines.append("~ = approximate start "
+                     "(no recorded Anthropic reset for this window)")
+
+    lines += ["", _b("Current Usage:"),
+              f"  Input Tokens:     {_fmt_num(block.input_tokens)}",
+              f"  Output Tokens:    {_fmt_num(block.output_tokens)}",
+              f"  Total Cost:       ${block.cost_usd:.2f}"]
+
+    if block.burn_rate:
+        lines += ["", _b("Burn Rate:"),
+                  f"  Tokens/minute:    "
+                  f"{_fmt_num(int(block.burn_rate['tokensPerMinute']))}",
+                  f"  Cost/hour:        ${block.burn_rate['costPerHour']:.2f}"]
+
+    if block.projection:
+        proj = block.projection
+        lines += ["", _b("Projected Usage (if current rate continues):"),
+                  f"  Total Tokens:     {_fmt_num(proj['totalTokens'])}",
+                  f"  Total Cost:       ${proj['totalCost']:.2f}"]
+        if token_limit_explicit is not None and token_limit_explicit > 0:
+            limit = token_limit_explicit
+            current = block.total_tokens
+            remaining_tokens = max(limit - current, 0)
+            pct_used = (proj["totalTokens"] / limit) * 100.0
+            cur_pct = (current / limit) * 100.0
+            # Keep the EXCEEDS/WARNING/OK thresholds (>100 / >80) in sync with
+            # the JSON status ladder in _lib_blocks._blocks_to_json.
+            if pct_used > 100:
+                status = _style_ansi("EXCEEDS LIMIT", "31", color)
+            elif pct_used > 80:
+                status = _style_ansi("WARNING", "33", color)
+            else:
+                status = _style_ansi("OK", "32", color)
+            lines += ["", _b("Token Limit Status:"),
+                      f"  Limit:            {_fmt_num(limit)} tokens",
+                      f"  Current Usage:    {_fmt_num(current)} ({cur_pct:.1f}%)",
+                      f"  Remaining:        {_fmt_num(remaining_tokens)} tokens",
+                      f"  Projected Usage:  {pct_used:.1f}% {status}"]
+    return "\n".join(lines)
+
+
 def _render_blocks_table(
     blocks: list[Block],
     breakdown: bool = False,
@@ -232,6 +350,7 @@ def _render_blocks_table(
     now: dt.datetime | None = None,
     tz: "ZoneInfo | None" = None,
     compact: bool = False,
+    token_limit: int | None = None,
 ) -> str:
     """Render blocks as a ccusage-style ANSI table with box-drawing borders.
 
@@ -268,9 +387,6 @@ def _render_blocks_table(
     def _cyan(s: str) -> str:
         return _style_ansi(s, "36", color)
 
-    def _bold(s: str) -> str:
-        return _style_ansi(s, "1", color)
-
     def _green(s: str) -> str:
         return _style_ansi(s, "32", color)
 
@@ -283,21 +399,10 @@ def _render_blocks_table(
     # ── time formatting ─────────────────────────────────────────────────
 
     def _fmt_time_local(ts: dt.datetime) -> str:
-        local = ts.astimezone(tz)
-        hour_12 = local.hour % 12
-        if hour_12 == 0:
-            hour_12 = 12
-        ampm = "a.m." if local.hour < 12 else "p.m."
-        return (
-            f"{local.year}-{local.month:02d}-{local.day:02d}, "
-            f"{hour_12}:{local.minute:02d}:{local.second:02d} {ampm}"
-        )
+        return _fmt_block_time_local(ts, tz)
 
     def _fmt_duration_hm(total_seconds: float) -> str:
-        total_minutes = int(total_seconds / 60)
-        h = total_minutes // 60
-        m = total_minutes % 60
-        return f"{h}h {m:02d}m"
+        return _fmt_block_duration_hm(total_seconds)
 
     def _fmt_gap_duration(total_seconds: float) -> str:
         total_minutes = int(total_seconds / 60)
@@ -307,19 +412,23 @@ def _render_blocks_table(
         return f"{h}h {m:02d}m gap" if m else f"{h}h gap"
 
     # ── determine if % column is needed ─────────────────────────────────
-    max_completed_tokens = 0
-    for b in blocks:
-        if not b.is_gap and not b.is_active and b.total_tokens > 0:
-            if b.total_tokens > max_completed_tokens:
-                max_completed_tokens = b.total_tokens
-    token_limit = 0
+    max_completed_tokens = _lib_blocks._max_completed_block_tokens(blocks)
     active_block: Block | None = None
     for b in blocks:
         if b.is_active and not b.is_gap:
             active_block = b
-    show_pct = max_completed_tokens > 0
-    if show_pct:
-        token_limit = max_completed_tokens
+    # ``token_limit`` param (#86 Session F): when caller passes an explicit
+    # limit, honor it directly (forces the %/REMAINING/PROJECTED surface even
+    # with no completed history, suppressed only when <= 0). When None, fall
+    # back to the internal auto-max recompute so the renderer stays
+    # standalone-callable and the default ``cmd_blocks`` path (which passes the
+    # resolved auto-max) is byte-identical.
+    if token_limit is not None:
+        show_pct = token_limit > 0
+        eff_limit = token_limit if token_limit > 0 else 0
+    else:
+        show_pct = max_completed_tokens > 0
+        eff_limit = max_completed_tokens if show_pct else 0
 
     # ── column layout ───────────────────────────────────────────────────
     headers = ["Block Start", "Duration/\u2026", "Models", "Tokens"]
@@ -405,8 +514,8 @@ def _render_blocks_table(
                 short_models = [""]
 
             pct_str = ""
-            if show_pct and token_limit > 0:
-                pct_val = (block.total_tokens / token_limit) * 100.0
+            if show_pct and eff_limit > 0:
+                pct_val = (block.total_tokens / eff_limit) * 100.0
                 pct_str = f"{pct_val:.1f}%"
 
             tokens_str = _fmt_num(block.total_tokens)
@@ -436,11 +545,11 @@ def _render_blocks_table(
 
     # Footer rows (REMAINING, PROJECTED)
     footer_rows: list[tuple[list[list[str]], str]] = []
-    if show_pct and token_limit > 0:
+    if show_pct and eff_limit > 0:
         active_tokens = active_block.total_tokens if active_block else 0
-        remaining_tokens = max(token_limit - active_tokens, 0)
-        remaining_pct = (remaining_tokens / token_limit) * 100.0
-        rem_label = f"(assuming {_fmt_num(token_limit)} token limit)"
+        remaining_tokens = max(eff_limit - active_tokens, 0)
+        remaining_pct = (remaining_tokens / eff_limit) * 100.0
+        rem_label = f"(assuming {_fmt_num(eff_limit)} token limit)"
 
         rem_cells = _empty_cells()
         rem_cells[0] = rem_label
@@ -456,7 +565,7 @@ def _render_blocks_table(
             proj = active_block.projection
             proj_tokens = proj.get("totalTokens", 0)
             proj_pct = (
-                (proj_tokens / token_limit) * 100.0 if token_limit > 0 else 0
+                (proj_tokens / eff_limit) * 100.0 if eff_limit > 0 else 0
             )
             proj_cost = proj.get("totalCost", 0.0)
 
@@ -600,23 +709,8 @@ def _render_blocks_table(
 
     # Title banner
     title = "Claude Code Token Usage Report - Session Blocks"
-    title_padded = f"  {title}  "
-    tw = len(title_padded)
-    dash = "\u2500" if unicode_ok else "-"
-    vb = "\u2502" if unicode_ok else "|"
-    if unicode_ok:
-        banner_top = f" \u256d{dash * tw}\u256e"
-        banner_bot = f" \u2570{dash * tw}\u256f"
-    else:
-        banner_top = f" +{'-' * tw}+"
-        banner_bot = f" +{'-' * tw}+"
-
     lines: list[str] = []
-    lines.append(banner_top)
-    lines.append(f" {vb}" + " " * tw + vb)
-    lines.append(f" {vb}" + _bold(title_padded) + vb)
-    lines.append(f" {vb}" + " " * tw + vb)
-    lines.append(banner_bot)
+    lines.append(_render_title_banner(title, unicode_ok=unicode_ok, color=color))
     lines.append("")
 
     # Header
@@ -680,6 +774,40 @@ def _render_blocks_table(
     return rendered
 
 
+def _daily_row_dict(d: BucketUsage, *, date_key: str) -> dict[str, Any]:
+    """Single bucket → upstream-shaped row dict.
+
+    Shared by `_bucket_to_json` and `_bucket_by_project_to_json` so the per-row
+    shape (field set + order) can never drift. Key order matches ccusage:
+      date_key, inputTokens, outputTokens, cacheCreationTokens,
+      cacheReadTokens, totalTokens, totalCost, modelsUsed, modelBreakdowns.
+    """
+    return {
+        date_key: d.bucket,
+        "inputTokens": d.input_tokens,
+        "outputTokens": d.output_tokens,
+        "cacheCreationTokens": d.cache_creation_tokens,
+        "cacheReadTokens": d.cache_read_tokens,
+        "totalTokens": d.total_tokens,
+        "totalCost": d.cost_usd,
+        "modelsUsed": list(d.models),
+        "modelBreakdowns": list(d.model_breakdowns),
+    }
+
+
+def _bucket_totals_dict(buckets) -> dict[str, Any]:
+    """Aggregate totals across buckets (key order matches ccusage; note
+    totalCost BEFORE totalTokens)."""
+    return {
+        "inputTokens": sum(b.input_tokens for b in buckets),
+        "outputTokens": sum(b.output_tokens for b in buckets),
+        "cacheCreationTokens": sum(b.cache_creation_tokens for b in buckets),
+        "cacheReadTokens": sum(b.cache_read_tokens for b in buckets),
+        "totalCost": sum(b.cost_usd for b in buckets),
+        "totalTokens": sum(b.total_tokens for b in buckets),
+    }
+
+
 def _bucket_to_json(
     buckets: list[BucketUsage],
     *,
@@ -696,43 +824,27 @@ def _bucket_to_json(
       cacheReadTokens, totalTokens, totalCost, modelsUsed, modelBreakdowns.
     Totals key order (note: totalCost BEFORE totalTokens, per ccusage).
     """
-    bucket_list: list[dict[str, Any]] = []
-    tot_input = 0
-    tot_output = 0
-    tot_cc = 0
-    tot_cr = 0
-    tot_cost = 0.0
-    tot_tokens = 0
-    for d in buckets:
-        bucket_list.append({
-            date_key: d.bucket,
-            "inputTokens": d.input_tokens,
-            "outputTokens": d.output_tokens,
-            "cacheCreationTokens": d.cache_creation_tokens,
-            "cacheReadTokens": d.cache_read_tokens,
-            "totalTokens": d.total_tokens,
-            "totalCost": d.cost_usd,
-            "modelsUsed": list(d.models),
-            "modelBreakdowns": list(d.model_breakdowns),
-        })
-        tot_input += d.input_tokens
-        tot_output += d.output_tokens
-        tot_cc += d.cache_creation_tokens
-        tot_cr += d.cache_read_tokens
-        tot_cost += d.cost_usd
-        tot_tokens += d.total_tokens
-
-    totals = {
-        "inputTokens": tot_input,
-        "outputTokens": tot_output,
-        "cacheCreationTokens": tot_cc,
-        "cacheReadTokens": tot_cr,
-        "totalCost": tot_cost,
-        "totalTokens": tot_tokens,
-    }
+    bucket_list = [_daily_row_dict(d, date_key=date_key) for d in buckets]
+    totals = _bucket_totals_dict(buckets)
     return json.dumps({list_key: bucket_list, "totals": totals}, indent=2)
 
 
+def _bucket_by_project_to_json(project_groups, *, date_key: str = "date") -> str:
+    """Serialize ``[(label, [BucketUsage]), ...]`` to ``{projects:{label:[rows]},
+    totals}`` (upstream ccusage daily --instances shape). Caller passes the
+    disambiguated (unique, non-aliased) label per group; insertion order is
+    preserved as the JSON key order."""
+    projects: dict[str, Any] = {}
+    all_buckets: list = []
+    for label, buckets in project_groups:
+        projects[label] = [_daily_row_dict(b, date_key=date_key) for b in buckets]
+        all_buckets.extend(buckets)
+    return json.dumps(
+        {"projects": projects, "totals": _bucket_totals_dict(all_buckets)},
+        indent=2,
+    )
+
+
 def _weekly_to_json(
     buckets: list[BucketUsage],
     weeks: list[SubWeek],
@@ -961,6 +1073,57 @@ def _codex_bucket_to_json(
     return json.dumps({list_key: bucket_list, "totals": totals}, indent=2)
 
 
+def _codex_root_short_labels(roots: list[str]) -> list[str]:
+    """Given >=2 distinct root paths, return a short distinguishing label per
+    root: the first path segment after their longest common ancestor — e.g.
+    {".../rootA/.codex", ".../rootB/.codex"} -> ["rootA", "rootB"]. If a single
+    segment isn't unique, fall back to the full post-ancestor tail, then to the
+    whole path, so the returned labels are always pairwise distinct.
+
+    Order-preserving: labels[i] corresponds to roots[i].
+    """
+    parts = [pathlib.PurePosixPath(r).parts for r in roots]
+    common = 0
+    for seg in zip(*parts):
+        if len(set(seg)) == 1:
+            common += 1
+        else:
+            break
+    singles = [pr[common] if common < len(pr) else (pr[-1] if pr else "")
+               for pr in parts]
+    if len(set(singles)) == len(singles):
+        return singles
+    tails = ["/".join(pr[common:]) or (pr[-1] if pr else "") for pr in parts]
+    if len(set(tails)) == len(tails):
+        return tails
+    return list(roots)
+
+
+def _codex_session_disambiguate(sessions: list[CodexSessionUsage]) -> dict[int, str]:
+    """Return ``{row_index: " (label)"}`` for codex-session rows whose
+    ``session_id_path`` collides with another row's — a genuine
+    cross-$CODEX_HOME-root collision (issue #110). Non-colliding rows are absent
+    from the dict; callers render them byte-identically (single-root data never
+    collides, so this returns ``{}`` and output is unchanged).
+
+    ``label`` is a short distinguishing segment of the matched $CODEX_HOME root
+    (see ``_codex_root_short_labels``). Mirrors ``_project_disambiguate_labels``.
+    """
+    path_counts: dict[str, int] = {}
+    for s in sessions:
+        path_counts[s.session_id_path] = path_counts.get(s.session_id_path, 0) + 1
+    groups: dict[str, list[int]] = {}
+    for idx, s in enumerate(sessions):
+        if path_counts[s.session_id_path] > 1:
+            groups.setdefault(s.session_id_path, []).append(idx)
+    out: dict[int, str] = {}
+    for idxs in groups.values():
+        labels = _codex_root_short_labels([sessions[i].codex_root for i in idxs])
+        for i, label in zip(idxs, labels):
+            out[i] = f" ({label})"
+    return out
+
+
 def _codex_sessions_to_json(sessions: list[CodexSessionUsage]) -> str:
     """Serialize Codex session aggregates to JSON matching upstream exactly.
 
@@ -972,9 +1135,13 @@ def _codex_sessions_to_json(sessions: list[CodexSessionUsage]) -> str:
     session_list: list[dict[str, Any]] = []
     tot_input = tot_cached = tot_output = tot_reasoning = tot_tokens = 0
     tot_cost = 0.0
-    for s in sessions:
+    # Issue #110: only when two cross-root sessions share `sessionId` (the
+    # relative path) does this map a colliding row to a label; otherwise empty,
+    # so the per-session shape stays upstream-byte-identical (no `codexRoot`).
+    disambig = _codex_session_disambiguate(sessions)
+    for idx, s in enumerate(sessions):
         session_total = s.input_tokens + s.output_tokens
-        session_list.append({
+        entry = {
             "sessionId": s.session_id_path,
             "lastActivity": _codex_last_activity_iso(s.last_activity),
             "sessionFile": s.session_file,
@@ -986,7 +1153,13 @@ def _codex_sessions_to_json(sessions: list[CodexSessionUsage]) -> str:
             "totalTokens": session_total,
             "costUSD": s.cost_usd,
             "models": _codex_models_dict(s.model_breakdowns),
-        })
+        }
+        if idx in disambig:
+            # Additive disambiguator — `sessionId` keeps its upstream-compatible
+            # relative-path value; consumers key off `codexRoot` to tell the
+            # (correctly separate) colliding rows apart.
+            entry["codexRoot"] = s.codex_root
+        session_list.append(entry)
         tot_input += s.input_tokens
         tot_cached += s.cached_input_tokens
         tot_output += s.output_tokens
@@ -1079,6 +1252,7 @@ def _render_bucket_table(
     compact_split_fn: Callable[[str], str],
     breakdown: bool = False,
     compact: bool = False,
+    project_groups=None,
 ) -> str:
     """Render bucket aggregates as a ccusage-style ANSI table.
 
@@ -1089,6 +1263,12 @@ def _render_bucket_table(
                          "YYYY\\n..." for compact-mode two-line display.
       compact         — force compact layout regardless of terminal width
                         (Session A `--compact` flag; spec §7.6.1).
+      project_groups  — when provided as ``[(label, [BucketUsage]), ...]``,
+                        render section layout: a ``Project: <label>`` header
+                        per group with one global Total footer summed across
+                        all groups (`daily -i/--instances`; issue #86 Session
+                        E). Default ``None`` = today's flat single-table
+                        behavior driven by ``buckets``.
 
     Mirrors ccusage's ResponsiveTable behavior: single-line headers and dates
     when content fits the terminal; falls back to two-line compact headers
@@ -1126,10 +1306,10 @@ def _render_bucket_table(
     # ── Build raw rows: each is (cells, row_type) where a cell is the
     #    tuple (text, color_fn_or_none). `text` may contain '\n' for
     #    multi-line cells (Models list, compact Date).
-    ROW_DATA, ROW_BREAKDOWN, ROW_FOOTER = "data", "breakdown", "footer"
+    ROW_DATA, ROW_BREAKDOWN, ROW_FOOTER, ROW_PROJECT = "data", "breakdown", "footer", "project"
     raw_rows: list[tuple[list[tuple[str, Any]], str]] = []
 
-    for d in buckets:
+    def _emit_data_and_breakdown(d):
         # ccusage formatModelsDisplayMultiline: uniq → sort alphabetical
         short_models = sorted({_short_model_name(m) for m in d.models})
         models_text = "\n".join(f"- {m}" for m in short_models) if short_models else ""
@@ -1166,13 +1346,30 @@ def _render_bucket_table(
                 ]
                 raw_rows.append((bd_cells, ROW_BREAKDOWN))
 
+    if project_groups is not None:
+        # Project-aware section layout (daily --instances): one cyan
+        # `Project: <label>` header per group, then that group's normal
+        # ROW_DATA (+ ROW_BREAKDOWN children); the single footer is computed
+        # by flattening all groups' buckets.
+        footer_buckets: list = []
+        for label, group_buckets in project_groups:
+            header_cells = [(f"Project: {label}", _cyan)] + [("", None)] * (num_cols - 1)
+            raw_rows.append((header_cells, ROW_PROJECT))
+            for d in group_buckets:
+                _emit_data_and_breakdown(d)
+                footer_buckets.append(d)
+    else:
+        for d in buckets:
+            _emit_data_and_breakdown(d)
+        footer_buckets = buckets
+
     # Total footer row — yellow on all populated cells.
-    tot_input = sum(d.input_tokens for d in buckets)
-    tot_output = sum(d.output_tokens for d in buckets)
-    tot_cc = sum(d.cache_creation_tokens for d in buckets)
-    tot_cr = sum(d.cache_read_tokens for d in buckets)
-    tot_tokens = sum(d.total_tokens for d in buckets)
-    tot_cost = sum(d.cost_usd for d in buckets)
+    tot_input = sum(d.input_tokens for d in footer_buckets)
+    tot_output = sum(d.output_tokens for d in footer_buckets)
+    tot_cc = sum(d.cache_creation_tokens for d in footer_buckets)
+    tot_cr = sum(d.cache_read_tokens for d in footer_buckets)
+    tot_tokens = sum(d.total_tokens for d in footer_buckets)
+    tot_cost = sum(d.cost_usd for d in footer_buckets)
     footer_cells = [
         ("Total", _yellow),
         ("", None),
@@ -2053,14 +2250,18 @@ def _render_codex_session_table(
     ROW_DATA, ROW_FOOTER = "data", "footer"
     raw_rows: list[tuple[list[tuple[str, Any]], str]] = []
 
-    for s in sessions:
+    # Issue #110: suffix the Session cell with the matched $CODEX_HOME root
+    # ONLY for cross-root collisions (two rows sharing session_id_path); empty
+    # for single-root data, so the table stays byte-identical.
+    disambig = _codex_session_disambiguate(sessions)
+    for idx, s in enumerate(sessions):
         models_text = "\n".join(f"- {m}" for m in s.models) if s.models else ""
         non_cached = max(0, s.input_tokens - s.cached_input_tokens)
         session_total = s.input_tokens + s.output_tokens
         data_cells = [
             (_date_cell(s.last_activity), None),
             (s.directory, None),
-            (_session_cell(s.session_id), None),
+            (_session_cell(s.session_id) + disambig.get(idx, ""), None),
             (models_text, None),
             (_fmt_num(non_cached), None),
             (_fmt_num(s.output_tokens), None),