fix(cli): tighten CLI errors and apply review fixes

Author: clean6378-max-it

pyproject.toml

@@ -5,6 +5,7 @@ packages = ["api", "utils", "models"]
 exclude = ["tests/"]
 
 [tool.pytest.ini_options]
+pythonpath = ["."]
 addopts = "--cov=api --cov=utils --cov-report=term-missing --cov-report=xml:coverage.xml --benchmark-skip"
 testpaths = ["tests"]
 markers = [

scripts/export.py

@@ -42,6 +42,7 @@
     ZipSink,
     bulk_export_exit_code,
     dominant_failure_code,
+    failure_code_for_exception,
     failure_message_for_code,
     run_bulk_export,
     serialize_manifest_jsonl,
@@ -182,7 +183,10 @@ def cmd_list(args):
     project_filter = getattr(args, "project", None)
 
     if not os.path.isdir(base_dir):
-        _die(ErrorCode.INTERNAL_ERROR, detail=f"Claude Code projects directory not found: {base_dir}")
+        _die(
+            ErrorCode.INTERNAL_ERROR,
+            detail=f"Claude Code projects directory not found: {base_dir}",
+        )
 
     projects = list_projects(base_dir)
     if project_filter:
@@ -228,8 +232,13 @@ def _list_sessions(project: dict):
             tokens = meta["total_input_tokens"] + meta["total_output_tokens"]
             tools = meta["total_tool_calls"]
             print(f"  {ts:<12} {title:<50} {sid:>10} {tokens:>10,} {tools:>6}")
-        except Exception as e:
-            print(f"  Warning: failed to parse {s['id'][:10]}: {e}", file=sys.stderr)
+        except Exception as exc:
+            code = failure_code_for_exception(exc)
+            print(
+                f"  Warning: failed to parse {s['id'][:10]}: "
+                f"{code.value} — {failure_message_for_code(code)}",
+                file=sys.stderr,
+            )
             continue
 
 
@@ -241,7 +250,10 @@ def cmd_stats(args):
     fmt = getattr(args, "format", "text") or "text"
 
     if not os.path.isdir(base_dir):
-        _die(ErrorCode.INTERNAL_ERROR, detail=f"Claude Code projects directory not found: {base_dir}")
+        _die(
+            ErrorCode.INTERNAL_ERROR,
+            detail=f"Claude Code projects directory not found: {base_dir}",
+        )
 
     if session_id:
         _session_stats(session_id, base_dir, fmt)
@@ -366,9 +378,11 @@ def _aggregate_stats(base_dir: str, project_filter: str, fmt: str):
                 if cost is not None:
                     totals["total_cost"] += cost
                     totals["has_cost"] = True
-            except Exception as e:
+            except Exception as exc:
+                code = failure_code_for_exception(exc)
                 print(
-                    f"  Warning: failed to parse {s['id'][:10]} in {project['name']}: {e}",
+                    f"  Warning: failed to parse {s['id'][:10]} in {project['name']}: "
+                    f"{code.value} — {failure_message_for_code(code)}",
                     file=sys.stderr,
                 )
                 continue
@@ -446,7 +460,10 @@ def cmd_export(args):
     exclusion_rules_path = getattr(args, "exclude_rules", None)
 
     if not os.path.isdir(base_dir):
-        _die(ErrorCode.INTERNAL_ERROR, detail=f"Claude Code projects directory not found: {base_dir}")
+        _die(
+            ErrorCode.INTERNAL_ERROR,
+            detail=f"Claude Code projects directory not found: {base_dir}",
+        )
 
     rules = load_rules(resolve_exclusion_rules_path(exclusion_rules_path))
 
@@ -757,8 +774,15 @@ def _save_state(sessions: dict, count: int, out_dir: str):
         atomic_write_export_state(disk, STATE_FILE)
 
 
+def _cli_die_message(code: ErrorCode) -> str:
+    """Stable CLI stderr label (not export-scoped)."""
+    if code == ErrorCode.INTERNAL_ERROR:
+        return "Command failed"
+    return failure_message_for_code(code)
+
+
 def _die(code: ErrorCode, *, detail: str | None = None) -> None:
-    print(f"Error: {code.value} — {failure_message_for_code(code)}", file=sys.stderr)
+    print(f"Error: {code.value} — {_cli_die_message(code)}", file=sys.stderr)
     if detail:
         print(detail, file=sys.stderr)
     sys.exit(1)

tests/test_cli_export_exit_codes.py

@@ -3,19 +3,20 @@
 from __future__ import annotations
 
 import re
-import sys
 import types
 from pathlib import Path
 
 import pytest
 
-REPO_ROOT = Path(__file__).resolve().parent.parent
-sys.path.insert(0, str(REPO_ROOT))
-
 import scripts.export as export
 from models.error_codes import ErrorCode
 from tests.test_cli_e2e import _run_cli, _seed_base_dir
-from utils.export_engine import BulkExportResult, ExportFailure, bulk_export_exit_code, dominant_failure_code
+from utils.export_engine import (
+    BulkExportResult,
+    ExportFailure,
+    bulk_export_exit_code,
+    dominant_failure_code,
+)
 from utils.jsonl_parser import parse_session
 
 _SUMMARY_RE = re.compile(

tests/test_error_codes.py

@@ -3,22 +3,16 @@
 from __future__ import annotations
 
 import json
-import sys
 import types
-from pathlib import Path
 
 import pytest
 
+import scripts.export as export_cli
 from api.error_codes import ErrorCode
 from api.search import _IndexSearchOutcome
 from tests.conftest import assert_error_response
 from tests.test_cli_e2e import _run_cli
 
-REPO_ROOT = Path(__file__).resolve().parent.parent
-sys.path.insert(0, str(REPO_ROOT))
-
-import scripts.export as export_cli
-
 
 @pytest.mark.parametrize(
     "method,path,kwargs,status,code",
@@ -108,13 +102,16 @@ def _raise_live_scan_failure(*_args, **_kwargs):
     [
         (["export", "--base-dir"], "INTERNAL_ERROR"),
         (["stats", "--base-dir"], "INTERNAL_ERROR"),
+        (["list", "--base-dir"], "INTERNAL_ERROR"),
     ],
 )
 def test_cli_missing_projects_dir_surfaces_error_code(tmp_path, argv: list[str], code: str) -> None:
     missing = tmp_path / "missing-claude-dir"
     proc = _run_cli([*argv, str(missing)])
     assert proc.returncode == 1
     assert code in proc.stderr
+    assert "Failed to export session" not in proc.stderr
+    assert "Command failed" in proc.stderr
     assert "Traceback" not in proc.stderr
 
 

tests/test_tool_dispatch_sync.py

@@ -42,17 +42,12 @@ def _format_set_diff(expected: frozenset[str], actual: frozenset[str], site: str
     return "; ".join(parts)
 
 
-def _parse_frontend_tool_use_renderers(path: Path) -> frozenset[str]:
-    """Extract ``TOOL_USE_RENDERERS`` keys.
-
-    Assumes values are bare identifiers (``Bash: renderBashUse``). Brace-depth
-    parsing avoids truncating the object body if a value ever contains ``}``.
-    """
+def _parse_frontend_registry_keys(path: Path, marker: str) -> frozenset[str]:
+    """Extract object keys from a ``registry.js`` export block (brace-depth safe)."""
     text = path.read_text(encoding="utf-8")
-    marker = "export const TOOL_USE_RENDERERS = {"
     start = text.find(marker)
     if start == -1:
-        msg = f"Could not find TOOL_USE_RENDERERS in {path}"
+        msg = f"Could not find {marker!r} in {path}"
         raise ValueError(msg)
     i = start + len(marker)
     depth = 1
@@ -65,37 +60,21 @@ def _parse_frontend_tool_use_renderers(path: Path) -> frozenset[str]:
             depth -= 1
         i += 1
     if depth != 0:
-        msg = f"Unbalanced braces in TOOL_USE_RENDERERS in {path}"
+        msg = f"Unbalanced braces after {marker!r} in {path}"
         raise ValueError(msg)
     body = text[body_start : i - 1]
     keys = re.findall(r"^\s*(\w+)\s*:", body, re.MULTILINE)
     return frozenset(keys)
 
 
+def _parse_frontend_tool_use_renderers(path: Path) -> frozenset[str]:
+    """Extract ``TOOL_USE_RENDERERS`` keys."""
+    return _parse_frontend_registry_keys(path, "export const TOOL_USE_RENDERERS = {")
+
+
 def _parse_frontend_tool_result_renderers(path: Path) -> frozenset[str]:
-    """Extract ``TOOL_RESULT_RENDERERS`` keys (brace-depth safe)."""
-    text = path.read_text(encoding="utf-8")
-    marker = "export const TOOL_RESULT_RENDERERS = {"
-    start = text.find(marker)
-    if start == -1:
-        msg = f"Could not find TOOL_RESULT_RENDERERS in {path}"
-        raise ValueError(msg)
-    i = start + len(marker)
-    depth = 1
-    body_start = i
-    while i < len(text) and depth > 0:
-        ch = text[i]
-        if ch == "{":
-            depth += 1
-        elif ch == "}":
-            depth -= 1
-        i += 1
-    if depth != 0:
-        msg = f"Unbalanced braces in TOOL_RESULT_RENDERERS in {path}"
-        raise ValueError(msg)
-    body = text[body_start : i - 1]
-    keys = re.findall(r"^\s*(\w+)\s*:", body, re.MULTILINE)
-    return frozenset(keys)
+    """Extract ``TOOL_RESULT_RENDERERS`` keys."""
+    return _parse_frontend_registry_keys(path, "export const TOOL_RESULT_RENDERERS = {")
 
 
 def _parse_dispatch_builder_result_types(path: Path) -> frozenset[str]:

utils/export_engine.py

@@ -5,9 +5,9 @@
 import json
 import posixpath
 import zipfile
+from collections import Counter
 from dataclasses import dataclass, field
 from datetime import date, datetime, timezone
-from collections import Counter
 from typing import Any, Callable, Literal, Protocol
 
 from models.error_codes import ErrorCode
@@ -95,24 +95,6 @@ def failure_message_for_code(code: ErrorCode) -> str:
     return "Export failed"
 
 
-def dominant_failure_code(failures: list[ExportFailure]) -> ErrorCode:
-    """Return the most common structured failure code in a bulk export run."""
-    if not failures:
-        msg = "failures must not be empty"
-        raise ValueError(msg)
-    counts = Counter(item.code for item in failures)
-    return counts.most_common(1)[0][0]
-
-
-def bulk_export_exit_code(result: BulkExportResult) -> int:
-    """Map structured bulk-export failures to CLI POSIX exit code (0/1/2)."""
-    if not result.failures:
-        return 0
-    if result.exported_session_count == 0:
-        return 1
-    return 2
-
-
 @dataclass
 class BulkExportResult:
     """Outcome of a bulk export run."""
@@ -136,6 +118,24 @@ def failure_count(self) -> int:
         return len(self.failures)
 
 
+def dominant_failure_code(failures: list[ExportFailure]) -> ErrorCode:
+    """Return the most common structured failure code in a bulk export run."""
+    if not failures:
+        msg = "failures must not be empty"
+        raise ValueError(msg)
+    counts = Counter(item.code for item in failures)
+    return counts.most_common(1)[0][0]
+
+
+def bulk_export_exit_code(result: BulkExportResult) -> int:
+    """Map structured bulk-export failures to CLI POSIX exit code (0/1/2)."""
+    if not result.failures:
+        return 0
+    if result.exported_session_count == 0:
+        return 1
+    return 2
+
+
 class ExportSink(Protocol):
     """Receives exported session files and final manifest."""