feat: initial implementation

Author: bradjin8

.github/workflows/tests.yml

@@ -132,11 +132,9 @@ jobs:
         run: dist\CursorChatBrowser\CursorChatBrowser.exe --help
 
   # ── Typecheck: mypy ───────────────────────────────────────────────────────
-  # Codebase already has type hints across most of the surface (~70+ typed
-  # functions). Mypy runs with --ignore-missing-imports for untyped
-  # third-party deps; strict-optional is enabled (mypy default). The
-  # transitional `continue-on-error: true` was removed in #29 once mypy
-  # reached zero errors on this repo — type failures now block merges.
+  # strict = true in pyproject.toml (issue #100). Per-module overrides skip
+  # scripts/export.py and tests/ until those surfaces are fully annotated.
+  # Type failures block merges — no continue-on-error.
   typecheck:
     name: Typecheck (mypy)
     runs-on: ubuntu-latest
@@ -157,9 +155,7 @@ jobs:
           python -m pip install 'mypy>=1.10,<2'
 
       - name: Run mypy
-        # No `continue-on-error` — mypy now exits zero on this repo (closes #29),
-        # so type errors must fail the job from here on.
-        run: mypy --ignore-missing-imports --pretty .
+        run: mypy .
 
   # ── Secret scan: gitleaks ─────────────────────────────────────────────────
   # Catches accidentally committed credentials. Runs over full git history

CHANGELOG.md

@@ -7,7 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.1.0] - 2026-06-04
+### Added
+- **Strict mypy** — `strict = true` in `pyproject.toml`; core TypedDict models
+  (`SearchResult`, `ConversationSummary`) and full annotations on API routes and
+  `utils/` (#100)
+
+### Changed
+- CI typecheck job runs `mypy .` using pyproject config (strict production code;
+  per-module overrides for `scripts/export.py` and `tests.*`)
 
 ### Added
 - **Summary disk cache (Phase 3)** — project list and tab summaries cached under

api/composers.py

@@ -9,8 +9,9 @@
 import os
 import sqlite3
 from contextlib import closing
+from typing import Any
 
-from flask import Blueprint, jsonify
+from flask import Blueprint, Response, jsonify
 
 from utils.workspace_path import resolve_workspace_path
 from utils.path_helpers import to_epoch_ms
@@ -20,13 +21,13 @@
 _logger = logging.getLogger(__name__)
 
 
-def _read_json_file(path: str):
+def _read_json_file(path: str) -> Any:
     with open(path, "r", encoding="utf-8") as f:
         return json.load(f)
 
 
 @bp.route("/api/composers")
-def list_composers():
+def list_composers() -> tuple[Response, int] | Response:
     try:
         workspace_path = resolve_workspace_path()
         composers = []
@@ -120,7 +121,7 @@ def list_composers():
 
 
 @bp.route("/api/composers/<composer_id>")
-def get_composer(composer_id):
+def get_composer(composer_id: str) -> tuple[Response, int] | Response:
     try:
         workspace_path = resolve_workspace_path()
 

api/config_api.py

@@ -11,7 +11,7 @@
 import subprocess
 import sys
 
-from flask import Blueprint, jsonify, request
+from flask import Blueprint, Response, jsonify, request
 
 from utils.path_validation import WorkspacePathError, validate_workspace_path
 from utils.workspace_path import set_workspace_path_override
@@ -21,7 +21,7 @@
 
 
 @bp.route("/api/detect-environment")
-def detect_environment():
+def detect_environment() -> Response:
     try:
         is_wsl = False
         is_remote = bool(
@@ -56,7 +56,7 @@ def detect_environment():
 
 
 @bp.route("/api/validate-path", methods=["POST"])
-def validate_path():
+def validate_path() -> tuple[Response, int] | Response:
     """Same path rules as POST /api/set-workspace: realpath, markers (issue #15)."""
     try:
         body = request.get_json(silent=True) or {}
@@ -97,7 +97,7 @@ def validate_path():
 
 
 @bp.route("/api/set-workspace", methods=["POST"])
-def set_workspace():
+def set_workspace() -> tuple[Response, int] | Response:
     # Reject non-dict JSON bodies (array / string / number / null). Without
     # this, get_json returns the value directly, the truthy fallback `or {}`
     # is bypassed, and `body.get("path", "")` raises AttributeError — which
@@ -126,7 +126,7 @@ def set_workspace():
 
 
 @bp.route("/api/get-username")
-def get_username():
+def get_username() -> Response:
     try:
         username = "YOUR_USERNAME"
 

api/export_api.py

@@ -12,6 +12,7 @@
 import zipfile
 from datetime import datetime
 from pathlib import Path
+from typing import Any, cast
 
 from flask import Blueprint, Response, jsonify, request
 
@@ -38,13 +39,13 @@ def _get_state_dir() -> str:
     return os.path.join(str(Path.home()), ".cursor-chat-browser")
 
 
-def _get_export_state() -> dict:
+def _get_export_state() -> dict[str, Any]:
     """Read the export state file."""
     state_path = os.path.join(_get_state_dir(), "export_state.json")
     if os.path.isfile(state_path):
         try:
             with open(state_path, "r", encoding="utf-8") as f:
-                return json.load(f)
+                return cast(dict[str, Any], json.load(f))
         except (json.JSONDecodeError, ValueError, OSError) as e:
             _logger.warning(
                 "Could not read export state from %s: %s",
@@ -54,7 +55,7 @@ def _get_export_state() -> dict:
     return {}
 
 
-def _save_export_state(count: int):
+def _save_export_state(count: int) -> None:
     """Save export state after an export."""
     state_dir = _get_state_dir()
     os.makedirs(state_dir, exist_ok=True)
@@ -68,14 +69,14 @@ def _save_export_state(count: int):
 
 
 @bp.route("/api/export/state")
-def get_export_state():
+def get_export_state() -> Response:
     """Return the last export timestamp."""
     state = _get_export_state()
     return jsonify(state)
 
 
 @bp.route("/api/export", methods=["POST"])
-def export_chats():
+def export_chats() -> tuple[Response, int] | Response:
     """Export chats as a zip archive.
 
     Exclusion rules (``EXCLUSION_RULES`` app config key) are evaluated against
@@ -112,7 +113,7 @@ def export_chats():
                 ws_id_to_slug[e["name"]] = slug(display)
 
         today = datetime.now().strftime("%Y-%m-%d")
-        exported = []
+        exported: list[dict[str, Any]] = []
         rules = exclusion_rules()
 
         # ── Database reading via service layer ────────────────────────────────

api/flask_config.py

@@ -2,9 +2,11 @@
 
 from __future__ import annotations
 
+from typing import Any
+
 from flask import current_app
 
 
-def exclusion_rules() -> list:
+def exclusion_rules() -> list[list[Any]]:
     """Return loaded exclusion rules from app config (empty list when unset)."""
     return current_app.config.get("EXCLUSION_RULES") or []

api/logs.py

@@ -10,8 +10,9 @@
 import sqlite3
 from contextlib import closing
 from datetime import datetime
+from typing import Any
 
-from flask import Blueprint, jsonify
+from flask import Blueprint, Response, jsonify
 
 from utils.workspace_path import resolve_workspace_path
 from utils.path_helpers import to_epoch_ms, warn_workspace_json_read
@@ -26,7 +27,7 @@ def _extract_chat_id_from_bubble_key(key: str) -> str | None:
 
 
 @bp.route("/api/logs")
-def get_logs():
+def get_logs() -> tuple[Response, int] | Response:
     try:
         workspace_path = resolve_workspace_path()
         logs = []
@@ -40,7 +41,7 @@ def get_logs():
                     conn.row_factory = sqlite3.Row
                     rows = conn.execute("SELECT key, value FROM cursorDiskKV WHERE key LIKE 'bubbleId:%'").fetchall()
 
-                chat_map: dict[str, list] = {}
+                chat_map: dict[str, list[Any]] = {}
                 for row in rows:
                     chat_id = _extract_chat_id_from_bubble_key(row["key"])
                     if not chat_id:

api/pdf.py

@@ -6,6 +6,7 @@
 import io
 import logging
 import re
+from typing import Any
 
 from flask import Blueprint, Response, jsonify, request
 
@@ -43,7 +44,7 @@ def _safe_text(text: str) -> str:
 
 
 @bp.route("/api/generate-pdf", methods=["POST"])
-def generate_pdf():
+def generate_pdf() -> tuple[Response, int] | Response:
     try:
         body = request.get_json(silent=True) or {}
         markdown_text = body.get("markdown", "")
@@ -52,10 +53,10 @@ def generate_pdf():
         from fpdf import FPDF
 
         class PDFDoc(FPDF):
-            def header(self):
+            def header(self) -> None:
                 pass
 
-            def footer(self):
+            def footer(self) -> None:
                 self.set_y(-15)
                 self.set_font("Helvetica", "I", 8)
                 self.cell(0, 10, f"Page {self.page_no()}/{{nb}}", align="C")
@@ -74,7 +75,7 @@ def footer(self):
         # Parse markdown line by line
         lines = markdown_text.split("\n")
         in_code_block = False
-        code_lines = []
+        code_lines: list[str] = []
 
         for line in lines:
             try:
@@ -179,7 +180,7 @@ def footer(self):
         return jsonify({"error": "Failed to generate PDF"}), 500
 
 
-def _render_code_block(pdf, code_text: str):
+def _render_code_block(pdf: Any, code_text: str) -> None:
     """Render a code block with a dark background."""
     pdf.ln(3)
     pdf.set_font("Courier", "", 8)

api/search.py

@@ -4,10 +4,11 @@
 """
 
 import logging
+from typing import Any
 
-from flask import Blueprint, current_app, jsonify, request
+from flask import Blueprint, Response, current_app, jsonify, request
 
-from models import ParseWarningCollector
+from models import ParseWarningCollector, SearchResult
 from services.search import (
     rank_results,
     search_cli_sessions,
@@ -21,7 +22,7 @@
 
 
 @bp.route("/api/search")
-def search():
+def search() -> tuple[Response, int] | Response:
     try:
         query = request.args.get("q", "").strip()
         search_type = request.args.get("type", "all")
@@ -34,7 +35,7 @@ def search():
         parse_warnings = ParseWarningCollector()
         query_lower = query.lower()
 
-        results = []
+        results: list[SearchResult] = []
         results.extend(
             search_global_storage(workspace_path, query, query_lower, rules, parse_warnings)
         )
@@ -46,7 +47,7 @@ def search():
                 search_cli_sessions(get_cli_chats_path(), query, query_lower, rules)
             )
 
-        payload: dict = {"results": rank_results(results)}
+        payload: dict[str, Any] = {"results": rank_results(results)}
         return jsonify(parse_warnings.attach_to(payload))
 
     except Exception:

api/workspaces.py

@@ -10,8 +10,9 @@
 import logging
 import os
 from datetime import datetime, timezone
+from typing import Any
 
-from flask import Blueprint, jsonify, request
+from flask import Blueprint, Response, jsonify, request
 
 from api.flask_config import exclusion_rules
 
@@ -55,14 +56,14 @@ def _request_nocache() -> bool:
 
 
 @bp.route("/api/workspaces")
-def list_workspaces():
+def list_workspaces() -> tuple[Response, int] | Response:
     try:
         workspace_path = resolve_workspace_path()
         rules = exclusion_rules()
         projects, warnings = list_workspace_projects(
             workspace_path, rules, nocache=_request_nocache(),
         )
-        payload: dict = {"projects": projects}
+        payload: dict[str, Any] = {"projects": projects}
         if warnings:
             payload["warnings"] = warnings
         return jsonify(payload)
@@ -76,7 +77,7 @@ def list_workspaces():
 # ---------------------------------------------------------------------------
 
 @bp.route("/api/workspaces/<workspace_id>")
-def get_workspace(workspace_id):
+def get_workspace(workspace_id: str) -> tuple[Response, int] | Response:
     try:
         if workspace_id == "global":
             return jsonify({
@@ -154,7 +155,7 @@ def get_workspace(workspace_id):
 # ---------------------------------------------------------------------------
 
 @bp.route("/api/workspaces/<workspace_id>/tabs")
-def get_workspace_tabs(workspace_id):
+def get_workspace_tabs(workspace_id: str) -> tuple[Response, int] | Response:
     if workspace_id.startswith("cli:"):
         try:
             return get_cli_workspace_tabs(workspace_id, exclusion_rules())
@@ -182,7 +183,7 @@ def get_workspace_tabs(workspace_id):
 # ---------------------------------------------------------------------------
 
 @bp.route("/api/workspaces/<workspace_id>/tabs/<composer_id>")
-def get_workspace_tab(workspace_id, composer_id):
+def get_workspace_tab(workspace_id: str, composer_id: str) -> tuple[Response, int] | Response:
     if workspace_id.startswith("cli:"):
         return jsonify({"error": "Per-tab lazy load is not supported for CLI workspaces"}), 400
     try: