claude-dev-env 1.38.0 → 1.39.0

package/hooks/pyproject.toml

@@ -0,0 +1,69 @@
+# Centralized configuration for hook tooling.
+#
+# Replaces the standalone hooks/mypy.ini and provides a single config surface
+# for mypy, ruff, and pytest invocations rooted under packages/claude-dev-env/hooks/.
+# C3 (mypy_integration walk-up) finds this file by walking parents from each
+# checked .py file and matching on the [tool.mypy] table.
+
+[tool.mypy]
+mypy_path = "."
+python_version = "3.13"
+ignore_missing_imports = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+no_implicit_optional = true
+strict_equality = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+extend-exclude = [
+    ".audit-trail",
+    ".claude",
+    "node_modules",
+    "__pycache__",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "W",
+    "I",
+    "B",
+    "UP",
+    "SIM",
+    "PL",
+]
+ignore = [
+    "E501",
+    "PLR0913",
+    "PLR2004",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"test_*.py" = ["B011", "PLR2004"]
+"*_test.py" = ["B011", "PLR2004"]
+"conftest.py" = ["B011"]
+
+[tool.coverage.run]
+branch = true
+omit = [
+    "test_*.py",
+    "*_test.py",
+    "conftest.py",
+    "__pycache__/*",
+    ".audit-trail/*",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+]

package/hooks/validators/mypy_integration.py

@@ -1,6 +1,7 @@
 """Mypy integration for static type checking."""
 
 import subprocess
+import tomllib
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -25,6 +26,43 @@ def check_mypy_available() -> bool:
         return False
 
 
+def _pyproject_contains_tool_mypy(pyproject_path: Path) -> bool:
+    try:
+        with pyproject_path.open("rb") as readable_handle:
+            parsed_toml = tomllib.load(readable_handle)
+    except (OSError, tomllib.TOMLDecodeError):
+        return False
+    tool_table = parsed_toml.get("tool", {})
+    return isinstance(tool_table, dict) and "mypy" in tool_table
+
+
+def find_pyproject_with_mypy_config(starting_file: Path) -> Path | None:
+    """Walk up from a starting file to locate a pyproject.toml that configures mypy.
+
+    The walk skips pyproject.toml files that do not declare a [tool.mypy]
+    table so that an unrelated package config (for example, a project root
+    pyproject.toml) does not shadow a hook-tree pyproject.toml that
+    actually configures the type checker.
+
+    Args:
+        starting_file: The file (or directory) the walk begins from. The walk
+            climbs through every parent directory in order.
+
+    Returns:
+        The first ``pyproject.toml`` Path that declares a ``[tool.mypy]``
+        table, or ``None`` when no such file exists between ``starting_file``
+        and the filesystem root.
+    """
+    pyproject_filename_for_lookup = "pyproject.toml"
+    resolved_starting_file = starting_file.resolve()
+    current_directory = resolved_starting_file.parent if resolved_starting_file.is_file() else resolved_starting_file
+    for each_candidate_directory in [current_directory, *current_directory.parents]:
+        candidate_pyproject = each_candidate_directory / pyproject_filename_for_lookup
+        if candidate_pyproject.is_file() and _pyproject_contains_tool_mypy(candidate_pyproject):
+            return candidate_pyproject
+    return None
+
+
 def run_mypy_check(files: list[Path]) -> MypyResult:
     """Run mypy on files."""
     if not files:
@@ -37,8 +75,16 @@ def run_mypy_check(files: list[Path]) -> MypyResult:
     if not py_files:
         return MypyResult(passed=True, output="No Python files", error_count=0)
 
+    config_argument: list[str] = []
+    for each_py_file in py_files:
+        discovered_pyproject = find_pyproject_with_mypy_config(Path(each_py_file))
+        if discovered_pyproject is not None:
+            config_argument = ["--config-file", str(discovered_pyproject)]
+            break
+
     result = subprocess.run(
-        ["mypy", "--ignore-missing-imports", "--no-error-summary"] + py_files,
+        ["mypy", *config_argument, "--ignore-missing-imports", "--no-error-summary"]
+        + py_files,
         capture_output=True,
         text=True,
     )

package/hooks/validators/run_all_validators.py

@@ -14,7 +14,7 @@ import time
 from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
-from typing import Any, Callable, Dict, List, Optional, Tuple
+from typing import Callable, Dict, List, Optional, Tuple
 
 from .health_check import get_system_health, get_validator_version, print_health_report
 from .mypy_integration import check_mypy_available, run_mypy_check
@@ -179,10 +179,10 @@ def print_header() -> None:
 
 
 def build_json_output(
-    results: List[Any],
+    results: List["ValidatorResult"],
     metrics: TimingMetrics,
     include_timing: bool,
-) -> Dict[str, Any]:
+) -> Dict[str, object]:
     """Build JSON output dictionary.
 
     Args:

package/hooks/validators/test_mypy_integration.py

@@ -3,7 +3,12 @@
 from pathlib import Path
 from unittest.mock import patch
 
-from .mypy_integration import MypyResult, check_mypy_available, run_mypy_check
+from .mypy_integration import (
+    MypyResult,
+    check_mypy_available,
+    find_pyproject_with_mypy_config,
+    run_mypy_check,
+)
 
 
 def test_mypy_result_dataclass() -> None:
@@ -25,3 +30,47 @@ def test_run_mypy_check_returns_passed_for_empty_files() -> None:
     result = run_mypy_check([])
     assert result.passed is True
     assert "No files" in result.output
+
+
+def test_find_pyproject_returns_pyproject_with_tool_mypy(tmp_path: Path) -> None:
+    project_root = tmp_path / "myproj"
+    nested_dir = project_root / "src" / "deep"
+    nested_dir.mkdir(parents=True)
+    project_pyproject = project_root / "pyproject.toml"
+    project_pyproject.write_text("[tool.mypy]\nignore_missing_imports = true\n")
+    target_file = nested_dir / "module.py"
+    target_file.write_text("x: int = 1\n")
+    found_path = find_pyproject_with_mypy_config(target_file)
+    assert found_path == project_pyproject
+
+
+def test_find_pyproject_skips_pyproject_without_tool_mypy(tmp_path: Path) -> None:
+    outer_root = tmp_path / "outer"
+    inner_root = outer_root / "inner"
+    inner_root.mkdir(parents=True)
+    outer_pyproject = outer_root / "pyproject.toml"
+    outer_pyproject.write_text("[tool.mypy]\nignore_missing_imports = true\n")
+    inner_pyproject = inner_root / "pyproject.toml"
+    inner_pyproject.write_text("[project]\nname = 'inner-package'\n")
+    target_file = inner_root / "module.py"
+    target_file.write_text("y: str = 'hello'\n")
+    found_path = find_pyproject_with_mypy_config(target_file)
+    assert found_path == outer_pyproject
+
+
+def test_find_pyproject_returns_none_when_no_match(tmp_path: Path) -> None:
+    isolated_dir = tmp_path / "isolated"
+    isolated_dir.mkdir()
+    target_file = isolated_dir / "module.py"
+    target_file.write_text("z: float = 1.0\n")
+    assert find_pyproject_with_mypy_config(target_file) is None
+
+
+def test_find_pyproject_handles_malformed_toml(tmp_path: Path) -> None:
+    project_root = tmp_path / "broken"
+    project_root.mkdir()
+    project_pyproject = project_root / "pyproject.toml"
+    project_pyproject.write_text("[tool.mypy\nbroken = true\n")
+    target_file = project_root / "module.py"
+    target_file.write_text("a = 1\n")
+    assert find_pyproject_with_mypy_config(target_file) is None

package/hooks/workflow/doc_gist_auto_publish.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""PostToolUse hook: auto-publish HTML files marked with the doc-gist sentinel.
+
+When Claude writes an .html file containing the marker
+`<!-- @publish-as-gist -->`, this hook invokes the doc-gist `gist_upload.py`
+script against that file and prints the resulting gist + htmlpreview URLs
+into the harness output so Claude can quote them back to the user.
+
+The marker is the on-demand trigger: HTML files without it are ignored. This
+keeps the hook silent for HTML that is part of code (React components, test
+fixtures, scraped pages) and active only for HTML Claude intentionally
+designed as a shareable artifact.
+
+The hook does not modify the file, does not block the write, and exits 0
+even on upload failure (failure is logged to stderr but does not break
+Claude's flow).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import subprocess
+import sys
+from pathlib import Path
+from typing import IO
+
+
+logging.basicConfig(stream=sys.stderr, level=logging.WARNING, format="%(message)s")
+
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from config.doc_gist_auto_publish_constants import (  # noqa: E402
+    ALL_TARGET_TOOL_NAMES,
+    HOOK_SUBPROCESS_TIMEOUT_SECONDS,
+    HTML_FILE_EXTENSION,
+    PUBLISH_SENTINEL,
+    UPLOAD_SCRIPT_RELATIVE_PATH,
+)
+
+
+def _read_hook_payload() -> dict[str, object]:
+    """Read the PostToolUse JSON payload from stdin. Empty/invalid payload exits clean."""
+    try:
+        payload = json.load(sys.stdin)
+    except json.JSONDecodeError as decode_error:
+        logging.warning("doc_gist_auto_publish: invalid JSON payload: %s", decode_error)
+        sys.exit(0)
+    if not isinstance(payload, dict):
+        sys.exit(0)
+    return payload
+
+
+def _resolve_target_path(payload: dict[str, object]) -> Path | None:
+    """Extract a writable .html file path from the hook payload, or None to skip."""
+    if payload.get("tool_name") not in ALL_TARGET_TOOL_NAMES:
+        return None
+    tool_input = payload.get("tool_input", {})
+    if not isinstance(tool_input, dict):
+        return None
+    raw_path = tool_input.get("file_path", "")
+    if not isinstance(raw_path, str) or not raw_path.lower().endswith(HTML_FILE_EXTENSION):
+        return None
+    candidate = Path(raw_path)
+    if not candidate.is_file():
+        return None
+    return candidate
+
+
+def _has_publish_sentinel(target_path: Path) -> bool:
+    """Read the HTML and check for the publish marker."""
+    try:
+        contents = target_path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        logging.warning("doc_gist_auto_publish: cannot read %s", target_path)
+        return False
+    return PUBLISH_SENTINEL in contents
+
+
+def _resolve_upload_script() -> Path:
+    """Locate the gist_upload.py script bundled with the doc-gist skill."""
+    plugin_root_argument = sys.argv[1] if len(sys.argv) > 1 else None
+    if plugin_root_argument:
+        return Path(plugin_root_argument) / UPLOAD_SCRIPT_RELATIVE_PATH
+    plugin_root_directory = Path(__file__).resolve().parent.parent.parent
+    return plugin_root_directory / UPLOAD_SCRIPT_RELATIVE_PATH
+
+
+def _invoke_upload(
+    script_path: Path,
+    target_path: Path,
+    out_stream: IO[str],
+    err_stream: IO[str],
+) -> None:
+    """Run gist_upload.py against target_path and surface its URLs to the harness."""
+    try:
+        completed = subprocess.run(
+            [sys.executable, str(script_path), "--input", str(target_path), "--no-open"],
+            check=False,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=HOOK_SUBPROCESS_TIMEOUT_SECONDS,
+        )
+    except FileNotFoundError:
+        logging.warning("doc_gist_auto_publish: gist_upload script not found: %s", script_path)
+        return
+    except subprocess.TimeoutExpired:
+        logging.warning("doc_gist_auto_publish: gist_upload timed out after %ds", HOOK_SUBPROCESS_TIMEOUT_SECONDS)
+        return
+    if completed.stderr:
+        err_stream.write(completed.stderr)
+    if completed.returncode != 0:
+        logging.warning("doc_gist_auto_publish: gist_upload exited %d", completed.returncode)
+        return
+    if completed.stdout:
+        out_stream.write(completed.stdout)
+
+
+def main() -> None:
+    """Entry point — process one PostToolUse event, exit 0 always.
+
+    Returns:
+        None — exits 0 on success or when no action is needed.
+    """
+    payload = _read_hook_payload()
+    target_path = _resolve_target_path(payload)
+    if target_path is None:
+        sys.exit(0)
+    if not _has_publish_sentinel(target_path):
+        sys.exit(0)
+    script_path = _resolve_upload_script()
+    if not script_path.is_file():
+        logging.warning("doc_gist_auto_publish: missing %s", script_path)
+        sys.exit(0)
+    _invoke_upload(script_path, target_path, sys.stdout, sys.stderr)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()