cctally 1.52.1 → 1.54.0

package/bin/_cctally_dashboard.py

@@ -147,7 +147,7 @@ What stays in bin/cctally:
   c.ORIGINAL_SYS_ARGV = list(sys.argv)``.
 - ``eprint``, ``now_utc_iso``, ``parse_iso_datetime``, ``open_db``,
   ``load_config``, ``save_config``, ``_now_utc``, ``_command_as_of``,
-  ``format_display_dt``, ``resolve_display_tz``,
+  ``format_display_dt``,
   ``normalize_display_tz_value``, ``_render_migration_error_banner``,
   ``_aggregate_daily``, ``_aggregate_monthly``, ``_aggregate_weekly``,
   ``_calculate_entry_cost``, ``_canonical_5h_window_key``,
@@ -305,7 +305,6 @@ from _cctally_core import (
 )
 from _lib_display_tz import (
     format_display_dt,
-    resolve_display_tz,
     normalize_display_tz_value,
     _compute_display_block,
 )
@@ -5284,10 +5283,22 @@ def _qs_str(q: dict, key: str, default: str | None) -> str | None:
     return vals[0] if vals else default
 
 
-# #177 S6: valid kind facets for the conversation search / find routes. Kept in
-# lockstep with ``_lib_conversation_query._SEARCH_KINDS`` (the kernel re-raises
-# ValueError on an unknown kind; the handlers reject with a 400 before the call).
-_CONV_SEARCH_KINDS = ("all", "prompts", "assistant", "tools", "thinking")
+# #177 S6 / #217 S2: valid kind facets for the conversation routes. Kept in
+# lockstep with the kernel (``_lib_conversation_query._SEARCH_KINDS`` /
+# ``_FIND_KINDS``; the kernel re-raises ValueError on an unknown kind, and the
+# handlers reject with a 400 BEFORE the call — ``_run_conversation_query``
+# collapses every kernel exception to a 500, so a per-route 4xx must be decided
+# in the handler, not via try/except around the kernel).
+#
+# P1-1 (load-bearing kind-validation SPLIT): the cross-session search route
+# accepts ``title`` and ``files``; the in-conversation ``/find`` route does NOT —
+# its kernel (``find_in_conversation``) indexes ``_FIND_KIND_COLUMNS[kind]``,
+# which has no ``title``/``files`` entry, so accepting them there would be a 500
+# KeyError. Two distinct tuples keep ``/find?kind=title`` and ``/find?kind=files``
+# a clean 400.
+_CONV_SEARCH_KINDS = (
+    "all", "prompts", "assistant", "tools", "thinking", "title", "files")
+_CONV_FIND_KINDS = ("all", "prompts", "assistant", "tools", "thinking")
 
 
 class _BadConversationFilter(Exception):
@@ -5472,6 +5483,15 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             # Live-tail SSE for the open reader (spec §2). Matched BEFORE the
             # <id> reader catch-all.
             self._handle_get_conversation_events(path)
+        elif path.startswith("/api/conversation/") and path.endswith("/export"):
+            # #217 S5: whole-session Markdown export (F1/F5). Matched BEFORE the
+            # <id> reader catch-all (same precedence as /outline).
+            self._handle_get_conversation_export(path)
+        elif path.startswith("/api/conversation/") and path.endswith("/prompts"):
+            # #217 S7: ordered main-thread prompt spine for session comparison
+            # (F10). Matched BEFORE the <id> reader catch-all (same precedence
+            # as /outline).
+            self._handle_get_conversation_prompts(path)
         elif path.startswith("/api/conversation/"):
             self._handle_get_conversation_detail(path)
         else:
@@ -7451,15 +7471,21 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         """Lazy-load the pure conversation query kernel (Plan 2, §3)."""
         return sys.modules["cctally"]._load_sibling("_lib_conversation_query")
 
-    def _parse_search_kind(self, q):
-        """Read + validate the ``kind`` facet shared by the conversation search
-        and find routes (#177 S6). Returns the kind on success, or ``None`` after
-        having ALREADY sent a 400 — callers just ``return`` on ``None``. Kept in
-        lockstep with the kernel's ``_SEARCH_KINDS`` via ``_CONV_SEARCH_KINDS``
-        (the kernel module is resolved lazily per-request, so the handler keeps a
-        literal tuple rather than reaching across that import edge for a nit)."""
+    def _parse_search_kind(self, q, valid=_CONV_SEARCH_KINDS):
+        """Read + validate the ``kind`` facet for a conversation route (#177 S6 /
+        #217 S2). Returns the kind on success, or ``None`` after having ALREADY
+        sent a 400 — callers just ``return`` on ``None``.
+
+        ``valid`` is the per-route kind set (P1-1 split): the cross-session search
+        route passes ``_CONV_SEARCH_KINDS`` (includes ``title``), the
+        in-conversation ``/find`` route passes ``_CONV_FIND_KINDS`` (excludes
+        ``title``/``files``), so ``/find?kind=title`` is a 400 here — never a 500
+        KeyError downstream in ``find_in_conversation``. Kept in lockstep with the
+        kernel's ``_SEARCH_KINDS`` / ``_FIND_KINDS`` (the kernel module is
+        resolved lazily per-request, so the handler keeps literal tuples rather
+        than reaching across that import edge for a nit)."""
         kind = _qs_str(q, "kind", "all")
-        if kind not in _CONV_SEARCH_KINDS:
+        if kind not in valid:
             self._respond_json(400, {"error": f"unknown kind: {kind}"})
             return None
         return kind
@@ -7615,15 +7641,19 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         """``GET /api/conversation/<session-id>`` — the reader (spec §3.2).
 
         The id is percent-decoded so clients that encode reserved chars
-        round-trip. Unknown id → 404. ``after``/``limit`` page the items.
+        round-trip. Unknown id → 404. ``after``/``before``/``tail``/``limit``
+        page the items; ``after``/``before``/``tail`` are mutually exclusive
+        (>1 supplied → 400). ``tail=1`` opens at the bottom; ``before=<id>``
+        pages backward (#217 S2 / U4).
         """
         if not self._require_transcripts_allowed():
             return
         import urllib.parse as _u
         # ``path`` is already query-stripped by ``do_GET`` (``self.path.split("?")``),
-        # so the cursor params (?after=/?limit=) live ONLY on the raw ``self.path``.
-        # Sibling handlers read ``self.path`` directly — the detail route must too,
-        # or every request re-serves the head and pagination is dead.
+        # so the cursor params (?after=/?before=/?tail=/?limit=) live ONLY on the
+        # raw ``self.path``. Sibling handlers read ``self.path`` directly — the
+        # detail route must too, or every request re-serves the head and
+        # pagination is dead.
         query_str = self.path.partition("?")[2]
         session_id = _u.unquote(path[len("/api/conversation/"):])
         if not session_id:
@@ -7631,10 +7661,21 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             return
         q = _u.parse_qs(query_str)
         after = _qs_str(q, "after", None)
+        before = _qs_str(q, "before", None)
+        tail = _qs_str(q, "tail", None) in ("1", "true", "yes")
         limit = _qs_int(q, "limit", 500)
+        # Mutual-exclusion 400 (#217 S2 / U4). The kernel ALSO raises ValueError
+        # on >1 cursor as its own invariant, but ``_run_conversation_query``
+        # collapses every kernel exception to a 500, so the 400 must be decided
+        # HERE, before the kernel call — this explicit pre-call check is the
+        # authoritative backstop for the handler path.
+        if sum(1 for x in (after is not None, before is not None, tail) if x) > 1:
+            self.send_error(400, "after/before/tail are mutually exclusive")
+            return
         ok, body = self._run_conversation_query(
             lambda conn: self._conversation_query().get_conversation(
-                conn, session_id, after=after, limit=limit),
+                conn, session_id, after=after, before=before, tail=tail,
+                limit=limit),
             "/api/conversation")
         if not ok:
             return
@@ -7755,6 +7796,13 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         FTS/LIKE search (spec §3.3). Matched BEFORE the ``<id>`` reader in
         ``do_GET``. ``kind`` (#177 S6) is validated to ``_CONV_SEARCH_KINDS``
         (else 400) before the kernel call.
+
+        #217 S2 / Filtered-search: the browse filters (date/project/cost/rebuild)
+        are parsed by the SAME ``_parse_conversation_filters`` the browse rail uses
+        (malformed → 400 already sent) and threaded into the kernel, applied as a
+        session-scope restriction across every kind. The 400s (bad kind, bad
+        filter) are decided HERE, before the kernel call — ``_run_conversation_query``
+        collapses kernel exceptions to a 500.
         """
         if not self._require_transcripts_allowed():
             return
@@ -7766,9 +7814,12 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
         kind = self._parse_search_kind(q)
         if kind is None:
             return
+        filters = self._parse_conversation_filters(q)
+        if filters is None:
+            return  # a 400 has already been sent
         ok, body = self._run_conversation_query(
             lambda conn: self._conversation_query().search_conversations(
-                conn, query, limit=limit, offset=offset, kind=kind),
+                conn, query, limit=limit, offset=offset, kind=kind, **filters),
             "/api/conversation/search")
         if not ok:
             return
@@ -7835,14 +7886,94 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             return
         self._respond_json(200, body)
 
+    def _handle_get_conversation_prompts(self, path: str) -> None:
+        """``GET /api/conversation/<sid>/prompts`` — ordered main-thread human
+        prompts + full text (#217 S7 F10, the session-comparison spine). Same
+        fail-closed transcript privacy gate as ``/outline`` —
+        ``_require_transcripts_allowed()`` ONLY (no ``_check_origin_csrf``: the
+        sibling transcript GETs gate on this predicate alone). Unknown id → 404.
+        """
+        if not self._require_transcripts_allowed():
+            return
+        import urllib.parse as _u
+        session_id = _u.unquote(path[len("/api/conversation/"):-len("/prompts")])
+        if not session_id:
+            self.send_error(404, "conversation not found")
+            return
+        ok, body = self._run_conversation_query(
+            lambda conn: self._conversation_query().get_conversation_prompts(conn, session_id),
+            "/api/conversation/prompts")
+        if not ok:
+            return
+        if body is None:
+            self.send_error(404, "conversation not found")
+            return
+        self._respond_json(200, body)
+
+    _CONV_EXPORT_SCOPES = ("all", "prompts", "chat", "recipe")
+
+    def _handle_get_conversation_export(self, path: str) -> None:
+        """``GET /api/conversation/<sid>/export?scope=<all|prompts|chat|recipe>``
+        — whole-session Markdown (issue #217 S5 F1/F5).
+
+        Same fail-closed transcript privacy gate as ``/outline`` / ``/payload``
+        / ``/find`` — ``_require_transcripts_allowed()`` ONLY. **No
+        ``_check_origin_csrf``** (Codex P0-1): the sibling transcript GETs gate
+        on this predicate alone; ``_check_origin_csrf`` rejects a missing
+        ``Origin`` and would make export STRICTER than its sibling reader routes.
+
+        ``scope`` is validated HERE, BEFORE the kernel (the
+        ``_run_conversation_query``-collapses-kernel-exceptions-to-500 gotcha —
+        an invalid scope is a clean 400, never a 500). Unknown session → 404.
+        Emits ``text/markdown; charset=utf-8`` (the client builds the download
+        Blob/filename, so no ``Content-Disposition`` is needed)."""
+        if not self._require_transcripts_allowed():
+            return
+        import urllib.parse as _u
+        session_id = _u.unquote(path[len("/api/conversation/"):-len("/export")])
+        q = _u.parse_qs(self.path.partition("?")[2])
+        scope = _qs_str(q, "scope", "all")
+        if scope not in self._CONV_EXPORT_SCOPES:
+            self._respond_json(400, {"error": f"unknown scope: {scope}"})
+            return
+        if not session_id:
+            self.send_error(404, "conversation not found")
+            return
+        ok, body = self._run_conversation_query(
+            lambda conn: self._conversation_query().get_conversation_export(
+                conn, session_id, scope),
+            "/api/conversation/export")
+        if not ok:
+            return
+        if body is None:
+            self.send_error(404, "conversation not found")
+            return
+        data = body.encode("utf-8")
+        self.send_response(200)
+        self.send_header("Content-Type", "text/markdown; charset=utf-8")
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
     def _handle_get_conversation_find(self, path: str) -> None:
         """``GET /api/conversation/<sid>/find?q=...&kind=...`` — in-conversation
         find → document-ordered rendered-turn anchors (#177 S6). Same fail-closed
         privacy gate as the sibling routes; unknown id → 404; an invalid ``kind``
         → 400. Matched BEFORE the ``<id>`` reader catch-all in ``do_GET``.
+
+        P1-1: validates against ``_CONV_FIND_KINDS`` (NOT the search set), so the
+        cross-session-only ``kind=title``/``files`` return 400 here, never a 500.
+
+        #217 S4 / I-1.2: ``regex``/``case`` are truthy params. An invalid regex
+        is PRE-COMPILED here, BEFORE dispatching to the kernel — exactly as the
+        detail route pre-validates ``after/before/tail`` — because
+        ``_run_conversation_query`` collapses every kernel exception to a 500, so
+        a ``re.error`` from the kernel's ``re.compile`` would otherwise leak as a
+        500 instead of the actionable 400 the client maps to "invalid regex".
         """
         if not self._require_transcripts_allowed():
             return
+        import re as _re
         import urllib.parse as _u
         session_id = _u.unquote(path[len("/api/conversation/"):-len("/find")])
         if not session_id:
@@ -7850,12 +7981,23 @@ class DashboardHTTPHandler(BaseHTTPRequestHandler):
             return
         q = _u.parse_qs(self.path.partition("?")[2])
         query = _qs_str(q, "q", "")
-        kind = self._parse_search_kind(q)
+        kind = self._parse_search_kind(q, valid=_CONV_FIND_KINDS)
         if kind is None:
             return
+        regex = _qs_str(q, "regex", None) in ("1", "true", "yes")
+        case = _qs_str(q, "case", None) in ("1", "true", "yes")
+        # Pre-validate the regex HERE (Codex P1): the kernel compiles the same
+        # pattern, but its ``re.error`` would be swallowed into the generic 500
+        # envelope below. Compiling first turns a bad pattern into a clean 400.
+        if regex:
+            try:
+                _re.compile(query, 0 if case else _re.IGNORECASE)
+            except _re.error as e:
+                self._respond_json(400, {"error": f"invalid regex: {e}"})
+                return
         ok, body = self._run_conversation_query(
             lambda conn: self._conversation_query().find_in_conversation(
-                conn, session_id, query, kind=kind),
+                conn, session_id, query, kind=kind, regex=regex, case=case),
             "/api/conversation/find")
         if not ok:
             return
@@ -8472,11 +8614,12 @@ def cmd_dashboard(args: argparse.Namespace) -> int:
     _c_boot.ORIGINAL_ENTRYPOINT = shutil.which("cctally")
     _c_boot._UPDATE_WORKER = UpdateWorker()
 
-    # Resolve display tz (--tz overrides config.display.tz). The dashboard's
-    # envelope-emitted display block (Tasks 11-12) reads this; for now,
-    # stash on args so downstream selectors can pick it up uniformly.
+    # Load config for the bind-host + expose-transcripts resolution below. (#217
+    # S1 / U7b: dropped the dead ``args._resolved_tz = resolve_display_tz(...)``
+    # write — nothing in the dashboard ever read it back; the envelope display
+    # block it was speculatively staged for was never wired. Each report
+    # subcommand resolves + reads its own ``args._resolved_tz`` independently.)
     config = load_config()
-    args._resolved_tz = resolve_display_tz(args, config)
 
     # Resolve bind host: --host flag > config.dashboard.bind > argparse default.
     # `--host` defaults to None (Task 2) so we can distinguish "user explicitly