cctally 1.8.2 → 1.10.0

package/bin/_lib_changelog.py

@@ -0,0 +1,44 @@
+"""Public helper: read the latest stamped release header from CHANGELOG.md.
+
+Read-only. Pure with respect to inputs (CHANGELOG.md contents). The
+historical name ``_release_read_latest_release_version`` carried a
+``_release_`` prefix because the helper originated with the release-
+automation work, but the function is not release-machinery: doctor,
+the share kernel, and ``cctally --version`` all read it. Lives in a
+public sibling so the maintainer-only release tooling can move to a
+private artifact without dragging the version reader with it.
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def _cctally():
+    """Call-time accessor for the ``cctally`` module (project memory
+    ``_cctally() accessor pattern``). Avoids module-top ``import cctally``
+    so monkeypatch-sensitive globals (``CHANGELOG_PATH`` and
+    ``RELEASE_HEADER_RE``) stay reachable for tests."""
+    return sys.modules["cctally"]
+
+
+def _read_latest_changelog_version() -> tuple[str, str] | None:
+    """Read latest ``## [X.Y.Z] - YYYY-MM-DD`` header from
+    ``CHANGELOG_PATH``. Returns ``(version, date)`` or ``None`` if the
+    file is missing or has no stamped release header.
+
+    Body is byte-equivalent to the original
+    ``_release_read_latest_release_version`` definition in ``bin/cctally``
+    (the rename is the only intentional change); the regex
+    ``RELEASE_HEADER_RE`` is read from the ``cctally`` module so any
+    in-process update to the pattern remains the single source of truth.
+    """
+    c = _cctally()
+    try:
+        text = c.CHANGELOG_PATH.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return None
+    m = c.RELEASE_HEADER_RE.search(text)
+    if not m:
+        return None
+    return (m.group(1), m.group(2))

package/bin/_lib_semver.py

@@ -76,7 +76,7 @@ def _release_compute_next_version(
         return _release_format_semver(nxt_maj, nxt_min, nxt_pat, prerelease_id, 1)
 
     if is_prerelease:
-        raise ValueError("current version is a prerelease; run 'cctally release finalize' first or use --bump in a prerelease bump")
+        raise ValueError("current version is a prerelease; run 'cctally-release finalize' first or use --bump in a prerelease bump")
 
     if kind == "patch":
         return _release_format_semver(cur_maj, cur_min, cur_pat + 1)

package/bin/_lib_share_templates.py

@@ -37,6 +37,9 @@ SHARE_CAPABLE_PANELS: frozenset[str] = frozenset({
     "blocks",
     "forecast",
     "sessions",
+    # Projects panel + modal (spec 2026-05-19-projects-panel-design.md).
+    # 9th share-capable panel — three templates land in this module.
+    "projects",
 })
 
 
@@ -289,8 +292,10 @@ def _release_version() -> str:
     at `bin/cctally:86`). Falls back to `"dev"` when CHANGELOG is unreadable
     or has no stamped release entry yet (pre-release dev builds).
 
-    Parallel to `_release_read_latest_release_version` in `bin/cctally` —
-    intentionally duplicated so the template module stays free of any
+    Parallel to `_lib_changelog._read_latest_changelog_version`
+    (re-exported on `bin/cctally` under the historical
+    `_release_read_latest_release_version` name) — intentionally
+    duplicated so the template module stays free of any
     `bin/cctally` import. If CHANGELOG header format changes, update both.
     """
     from pathlib import Path
@@ -1550,6 +1555,176 @@ def _build_sessions_detail(*, panel_data, options):
     )
 
 
+# --- Projects panel + modal builders (spec §7.6) ---
+#
+# The three Projects-panel templates share a single internal kernel so
+# the table / chart / KPI layout stays consistent across archetypes:
+# only the "what's emphasized" shape differs (recap = top-N table,
+# visual = chart-forward, detail = full table + chart). All three
+# consume `panel_data` from `_build_projects_share_panel_data` in
+# `bin/_cctally_dashboard.py`, NOT `_build_project_snapshot` directly —
+# that kernel takes `ProjectKey` objects, but the dashboard envelope
+# emits already-disambiguated string `key`s. Both paths end up at the
+# same column shape: `Project | $ Cost | % Used | Sessions`.
+
+_PROJECTS_TABLE_COLUMNS = (
+    _LS.ColumnSpec(key="project", label="Project", align="left"),
+    _LS.ColumnSpec(key="cost",    label="$ Cost",  align="right", emphasis=True),
+    _LS.ColumnSpec(key="used",    label="% Used",  align="right"),
+    _LS.ColumnSpec(key="sessions", label="Sessions", align="right"),
+)
+
+
+def _projects_rows_for_template(rows: list[dict], cap: int) -> tuple:
+    """Build `Row` tuple for the Projects table from the dashboard
+    panel_data row shape.
+
+    `rows` is a list of dicts {key, bucket_path, cost_usd,
+    attributed_pct, sessions_count} (post-disambiguation, sorted by
+    caller). `cap` truncates to top-N by caller order. Mirrors
+    `_build_project_snapshot`'s row layout in bin/cctally:11774 but
+    with string keys (no ProjectKey objects).
+    """
+    out: list = []
+    for r in (rows or [])[:cap]:
+        attr = r.get("attributed_pct")
+        out.append(_LS.Row(cells={
+            "project":  _LS.ProjectCell(label=str(r["key"])),
+            "cost":     _LS.MoneyCell(usd=float(r["cost_usd"])),
+            "used":     (
+                _LS.PercentCell(float(attr)) if attr is not None
+                else _LS.TextCell("—")
+            ),
+            "sessions": _LS.TextCell(str(int(r.get("sessions_count", 0) or 0))),
+        }))
+    return tuple(out)
+
+
+def _projects_chart_for_template(rows: list[dict], cap: int):
+    """Build the HorizontalBarChart for the Projects share artifact.
+    Cap=12 mirrors `_build_project_snapshot` (bin/cctally:11813).
+    """
+    if not rows:
+        return None
+    points = []
+    for r in rows[:cap]:
+        label = str(r["key"])
+        cost = float(r["cost_usd"])
+        points.append(_LS.ChartPoint(
+            x_label=label,
+            x_value=cost,
+            y_value=cost,
+            project_label=label,
+        ))
+    return _LS.HorizontalBarChart(
+        points=tuple(points), x_label="$", cap=cap,
+    )
+
+
+def _projects_period(panel_data: dict, options: dict):
+    start = panel_data["period_start"]
+    end = panel_data["period_end"]
+    weeks = int(panel_data.get("window_weeks", 1) or 1)
+    label = "This week" if weeks == 1 else f"Last {weeks} weeks"
+    return _period(start, end, label=label,
+                   display_tz=_display_tz(options))
+
+
+def _projects_subtitle(options: dict, total_rows: int) -> str:
+    reveal = options.get("reveal_projects", True)
+    return " · ".join([
+        f"{total_rows} project{'' if total_rows == 1 else 's'}",
+        "real projects" if reveal else "projects anonymized",
+    ])
+
+
+def _build_projects_recap(*, panel_data, options):
+    """Projects recap — top-N table + KPI strip + HBar chart.
+
+    Mirrors `weekly-recap`'s balanced shape (table + chart + KPIs).
+    Top-N defaults to 5 (matches the panel's top-5 rows from spec §2.3).
+    """
+    rows = panel_data.get("rows") or []
+    cap = int(options.get("top_n", 5))
+    total = float(panel_data.get("total_cost_usd", 0.0) or 0.0)
+    return _LS.ShareSnapshot(
+        cmd="projects",
+        title=f"Projects recap — top {min(cap, len(rows))}",
+        subtitle=_projects_subtitle(options, len(rows)),
+        period=_projects_period(panel_data, options),
+        columns=_PROJECTS_TABLE_COLUMNS,
+        rows=_projects_rows_for_template(rows, cap),
+        chart=_projects_chart_for_template(rows, cap=12),
+        totals=_kpi_strip(
+            ("$ spent", f"${total:,.2f}"),
+            ("Projects", str(len(rows))),
+        ),
+        notes=(),
+        generated_at=_utc_now(),
+        version=_release_version(),
+    )
+
+
+def _build_projects_visual(*, panel_data, options):
+    """Projects visual — chart-forward HBar of top-12 projects by cost.
+
+    Mirrors `weekly-visual` / `current-week-visual` — chart-led, no
+    table. Spec §7.6 routes the visual archetype to a HorizontalBarChart
+    of the top-12 projects.
+    """
+    rows = panel_data.get("rows") or []
+    cap_chart = 12
+    total = float(panel_data.get("total_cost_usd", 0.0) or 0.0)
+    return _LS.ShareSnapshot(
+        cmd="projects",
+        title=f"Projects — top {min(cap_chart, len(rows))} by cost",
+        subtitle=_projects_subtitle(options, len(rows)),
+        period=_projects_period(panel_data, options),
+        columns=_PROJECTS_TABLE_COLUMNS,
+        rows=(),                                  # visual archetype: empty table
+        chart=_projects_chart_for_template(rows, cap=cap_chart),
+        totals=_kpi_strip(
+            ("$ spent", f"${total:,.2f}"),
+            ("Projects", str(len(rows))),
+        ),
+        notes=(),
+        generated_at=_utc_now(),
+        version=_release_version(),
+    )
+
+
+def _build_projects_detail(*, panel_data, options):
+    """Projects detail — full table + chart. Closest fit to today's CLI
+    `cctally project --format` output (spec §7.6 routes detail here).
+
+    Default top_n=50 means "all rows" for typical caches.
+    """
+    rows = panel_data.get("rows") or []
+    cap = int(options.get("top_n", 50))
+    total = float(panel_data.get("total_cost_usd", 0.0) or 0.0)
+    notes: tuple[str, ...] = ()
+    if len(rows) > 12:
+        notes = (
+            f"Showing top 12 in chart; table includes all {len(rows)}.",
+        )
+    return _LS.ShareSnapshot(
+        cmd="projects",
+        title=f"Projects detail — {len(rows)} project{'' if len(rows) == 1 else 's'}",
+        subtitle=_projects_subtitle(options, len(rows)),
+        period=_projects_period(panel_data, options),
+        columns=_PROJECTS_TABLE_COLUMNS,
+        rows=_projects_rows_for_template(rows, cap),
+        chart=_projects_chart_for_template(rows, cap=12),
+        totals=_kpi_strip(
+            ("$ spent",  f"${total:,.2f}"),
+            ("Projects", str(len(rows))),
+        ),
+        notes=notes,
+        generated_at=_utc_now(),
+        version=_release_version(),
+    )
+
+
 # --- Register Recap templates ---
 
 _RECAP = (
@@ -1585,6 +1760,11 @@ _RECAP = (
                   description="Top-N sessions table + total",
                   default_options={"top_n": 15, "show_chart": False, "show_table": True},
                   builder=_build_sessions_recap),
+    # Projects panel + modal (spec §7.6).
+    ShareTemplate(id="projects-recap", panel="projects", label="Recap",
+                  description="Top-N projects table + total + HBar chart",
+                  default_options={"top_n": 5, "show_chart": True, "show_table": True},
+                  builder=_build_projects_recap),
 )
 
 SHARE_TEMPLATES = SHARE_TEMPLATES + _RECAP
@@ -1625,6 +1805,11 @@ _VISUAL = (
                   description="Horizontal bar of top-N sessions by cost",
                   default_options={"top_n": 8, "show_chart": True, "show_table": False},
                   builder=_build_sessions_visual),
+    # Projects panel + modal (spec §7.6).
+    ShareTemplate(id="projects-visual", panel="projects", label="Visual",
+                  description="Chart-forward HBar of top-12 projects by cost",
+                  default_options={"top_n": 12, "show_chart": True, "show_table": False},
+                  builder=_build_projects_visual),
 )
 
 
@@ -1663,6 +1848,13 @@ _DETAIL = (
                   description="Top-50 sessions with full columns",
                   default_options={"top_n": 50, "show_chart": False, "show_table": True},
                   builder=_build_sessions_detail),
+    # Projects panel + modal (spec §7.6). Default top_n=50 means "all
+    # rows" for typical caches; matches today's CLI `cctally project
+    # --format` table shape.
+    ShareTemplate(id="projects-detail", panel="projects", label="Detail",
+                  description="Full projects table + HBar chart (top-12)",
+                  default_options={"top_n": 50, "show_chart": True, "show_table": True},
+                  builder=_build_projects_detail),
 )
 
 SHARE_TEMPLATES = SHARE_TEMPLATES + _VISUAL + _DETAIL

package/bin/_lib_view_models.py

@@ -243,6 +243,20 @@ class TuiSessionRow:
     cache_hit_pct: float | None
     project_label: str           # basename of project_path
     session_id: str              # full session UUID (v2: needed for session-detail modal)
+    # Disambiguated display key (matches the Projects panel envelope's
+    # `current_week.rows[].key` / `trend.projects[].key`). Populated by
+    # the sync-thread builder after `_build_projects_envelope` runs so
+    # the SessionsPanel → ProjectsModal cross-nav (spec §4.1) routes by
+    # a stable identity. Defaults to ``None`` for fixture modules that
+    # construct ``TuiSessionRow`` positionally without the Bundle 6 /
+    # projects-panel additions; the client renders the cell as plain
+    # text in that case per spec §4.1 stopgap.
+    project_key: str | None = None
+    # Absolute project_path (NULL ⇒ ``(unknown)`` resolved upstream).
+    # Carried so the sync-thread builder can compute ``project_key``
+    # without re-reading ``session_files`` and so the share path can
+    # privacy-scrub via ``_lib_share._scrub``.
+    project_path: str | None = None
 
 
 # === Internal helpers ======================================================
@@ -1066,6 +1080,12 @@ def build_sessions_view(entries, *, now_utc, limit=None, display_tz=None):
                 _os.path.basename(s.project_path) or s.project_path
             ),
             session_id=s.session_id,
+            # `project_key` is populated downstream by `_tui_build_snapshot`
+            # after `_build_projects_envelope` runs (so the disambiguated
+            # display_key matches the Projects envelope exactly). Stash
+            # the absolute path here so that pass can map back without
+            # re-reading session_files.
+            project_path=s.project_path or None,
         ))
         total_cost += s.cost_usd