claude-dev-env 4.2.0 → 4.3.0

package/.agents/skills/pull-request/scripts/test_recover_legacy_author.py

@@ -0,0 +1,221 @@
+"""Contract tests for explicit legacy GitHub author recovery."""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import subprocess
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from unittest.mock import Mock
+
+import pytest
+
+_SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIRECTORY))
+
+import recover_legacy_author
+
+CURRENT_TIME_SECONDS = 2_000_000.0
+CURRENT_USER_ID = 41
+LEGACY_ACCOUNT = "previous-account"
+OTHER_ACCOUNT = "other-account"
+STATE_FILENAME = "gh_pr_author_swap_session-a.json"
+
+
+def _completion(
+    code: int = 0, stdout: str = "", stderr: str = ""
+) -> subprocess.CompletedProcess[str]:
+    return subprocess.CompletedProcess([], code, stdout, stderr)
+
+
+def _write_state(
+    directory: Path,
+    *,
+    filename: str = STATE_FILENAME,
+    payload: object | None = None,
+    age_seconds: float = 1801.0,
+) -> Path:
+    state_file = directory / filename
+    state_payload = {"original_account": LEGACY_ACCOUNT} if payload is None else payload
+    state_file.write_text(json.dumps(state_payload), encoding="utf-8")
+    os.utime(
+        state_file,
+        (CURRENT_TIME_SECONDS - age_seconds, CURRENT_TIME_SECONDS - age_seconds),
+    )
+    if hasattr(os, "getuid"):
+        state_file.chmod(0o600)
+    return state_file
+
+
+def _run(
+    state_file: Path,
+    command_runner: Callable[..., subprocess.CompletedProcess[str]],
+    *,
+    confirm_inactive: bool = True,
+) -> int:
+    all_arguments = [str(state_file)]
+    if confirm_inactive:
+        all_arguments.append("--confirm-inactive")
+    return recover_legacy_author.main(
+        all_arguments,
+        now_seconds=CURRENT_TIME_SECONDS,
+        current_user_id=os.getuid() if hasattr(os, "getuid") else None,
+        command_runner=command_runner,
+    )
+
+
+def test_success_restores_selected_record_and_preserves_neighbor(
+    tmp_path: Path,
+) -> None:
+    selected_file = _write_state(tmp_path)
+    neighbor_file = _write_state(
+        tmp_path,
+        filename="gh_pr_author_swap_session-b.json",
+        payload={"original_account": OTHER_ACCOUNT},
+    )
+    command_runner = Mock(return_value=_completion())
+    assert _run(selected_file, command_runner) == 0
+    command_runner.assert_called_once_with(
+        ["gh", "auth", "switch", "--user", LEGACY_ACCOUNT],
+        capture_output=True,
+        check=False,
+        shell=False,
+        text=True,
+    )
+    assert not selected_file.exists()
+    assert neighbor_file.exists()
+
+
+def test_unconfirmed_record_is_unresolved_without_side_effects(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    state_file = _write_state(tmp_path)
+    command_runner = Mock()
+    assert _run(state_file, command_runner, confirm_inactive=False) == 3
+    assert "confirm inactive" in capsys.readouterr().err
+    command_runner.assert_not_called()
+    assert state_file.exists()
+
+
+def test_active_record_is_rejected_without_side_effects(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    state_file = _write_state(tmp_path, age_seconds=10.0)
+    command_runner = Mock()
+    assert _run(state_file, command_runner) == 2
+    assert "record is active" in capsys.readouterr().err
+    command_runner.assert_not_called()
+    assert state_file.exists()
+
+
+@pytest.mark.parametrize(
+    "payload",
+    [
+        [],
+        {},
+        {"original_account": ""},
+        {"original_account": 7},
+        {"original_account": LEGACY_ACCOUNT, "extra": True},
+    ],
+)
+def test_invalid_schema_is_rejected(
+    tmp_path: Path, payload: object, capsys: pytest.CaptureFixture[str]
+) -> None:
+    state_file = _write_state(tmp_path, payload=payload)
+    command_runner = Mock()
+    assert _run(state_file, command_runner) == 2
+    assert "record is invalid" in capsys.readouterr().err
+    command_runner.assert_not_called()
+    assert state_file.exists()
+
+
+def test_invalid_utf8_is_rejected(tmp_path: Path) -> None:
+    state_file = _write_state(tmp_path)
+    state_file.write_bytes(b"\xff")
+    os.utime(state_file, (CURRENT_TIME_SECONDS - 1801, CURRENT_TIME_SECONDS - 1801))
+    command_runner = Mock()
+    assert _run(state_file, command_runner) == 2
+    command_runner.assert_not_called()
+    assert state_file.exists()
+
+
+def test_wrong_filename_is_rejected(tmp_path: Path) -> None:
+    state_file = _write_state(tmp_path, filename="other.json")
+    command_runner = Mock()
+    assert _run(state_file, command_runner) == 2
+    command_runner.assert_not_called()
+
+
+def test_symlink_is_rejected(tmp_path: Path) -> None:
+    target_file = _write_state(tmp_path)
+    link_file = tmp_path / "gh_pr_author_swap_link.json"
+    try:
+        link_file.symlink_to(target_file)
+    except OSError as error:
+        pytest.skip(f"symlink unavailable: {error}")
+    command_runner = Mock()
+    assert _run(link_file, command_runner) == 2
+    command_runner.assert_not_called()
+    assert target_file.exists()
+
+
+def test_failed_restore_preserves_record_and_hides_child_output(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    state_file = _write_state(tmp_path)
+    command_runner = Mock(
+        return_value=_completion(1, LEGACY_ACCOUNT, f"unsafe {LEGACY_ACCOUNT}")
+    )
+    assert _run(state_file, command_runner) == 1
+    captured = capsys.readouterr()
+    assert captured.err == "error: GitHub account restore failed\n"
+    assert LEGACY_ACCOUNT not in captured.out + captured.err
+    assert state_file.exists()
+
+
+def test_restore_launch_failure_preserves_record(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    state_file = _write_state(tmp_path)
+    command_runner = Mock(side_effect=OSError("unavailable"))
+    assert _run(state_file, command_runner) == 1
+    assert capsys.readouterr().err == "error: GitHub account restore failed\n"
+    assert state_file.exists()
+
+
+def test_changed_record_after_restore_is_preserved(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    state_file = _write_state(tmp_path)
+
+    def change_record(
+        all_arguments: list[str], **keyword_arguments: object
+    ) -> subprocess.CompletedProcess[str]:
+        state_file.write_text(
+            json.dumps({"original_account": OTHER_ACCOUNT}), encoding="utf-8"
+        )
+        return _completion()
+
+    assert _run(state_file, change_record) == 1
+    assert "record changed" in capsys.readouterr().err
+    assert state_file.exists()
+
+
+def test_secure_posix_metadata_requires_regular_owner_mode() -> None:
+    regular_secure_mode = stat.S_IFREG | 0o600
+    assert recover_legacy_author._posix_metadata_is_secure(
+        regular_secure_mode, CURRENT_USER_ID, CURRENT_USER_ID
+    )
+    assert not recover_legacy_author._posix_metadata_is_secure(
+        regular_secure_mode, CURRENT_USER_ID + 1, CURRENT_USER_ID
+    )
+    assert not recover_legacy_author._posix_metadata_is_secure(
+        stat.S_IFREG | 0o644, CURRENT_USER_ID, CURRENT_USER_ID
+    )
+    assert not recover_legacy_author._posix_metadata_is_secure(
+        stat.S_IFLNK | 0o600, CURRENT_USER_ID, CURRENT_USER_ID
+    )

package/.agents/skills/test-runner/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: test-runner
+description: >-
+  Run pytest or Playwright through the repository's test command.
+  Checks Django and Playwright readiness before launching the
+  selected child process. Use when running tests in a repository with local
+  Django or frontend services.
+---
+
+# test-runner
+
+Run Django and Playwright readiness checks, then launch the selected test
+command. Pass one supported runner after `--`. The command forwards those
+arguments without a shell.
+
+## Command
+
+Run from the repository that owns the tests:
+
+```text
+python "${CLAUDE_SKILL_DIR}/scripts/run_tests.py" -- python -m pytest <pytest-arguments>
+python "${CLAUDE_SKILL_DIR}/scripts/run_tests.py" -- npx playwright test <playwright-arguments>
+```
+
+Use `--project <path>` when the test repository is not the current directory:
+
+```text
+python "${CLAUDE_SKILL_DIR}/scripts/run_tests.py" --project "<repository>" -- python -m pytest <pytest-arguments>
+```
+
+The supported runner forms are `pytest`, `python -m pytest`, `playwright test`,
+and `npx playwright test`. The child receives the exact arguments after `--`,
+inherits the current environment, writes to the current output streams, runs
+with the selected project as its working directory, and returns its exit
+status.
+
+## Preflight
+
+The command returns nonzero and launches no child when a required check fails.
+
+- A pytest run in a project without `manage.py` runs without preflight.
+- A pytest run in a Django project requires `db.sqlite3` and a healthy Django
+  server. The URL defaults to `http://localhost:8000`. A URL in the child
+  arguments overrides that default.
+- A Playwright run checks its target server, validates a detected Django
+  `runserver` process uses `--test-db`, rejects conflicting Django servers from
+  different worktrees, and uses the URL default `http://localhost:3000`.
+- When the project contains `frontend/`, the command runs `npm run build` in
+  that directory, then `python manage.py collectstatic --noinput` in the
+  project directory before Playwright starts.
+
+The command does not parse shell syntax. Keep pipes, redirects, `cd`, and
+background operators outside this command. Run this command directly so its
+exit status reaches the caller.
+
+## Unsupported commands
+
+Use the normal runner for anything else. This command accepts only the four
+runner forms listed above. It does not install dependencies, start a server,
+run migrations, or repair a failed preflight.
+
+## Files
+
+- `SKILL.md` covers invocation, checks, and the command boundary.
+- `scripts/run_tests.py` parses the command, runs preflight, and launches the child.
+- `scripts/preflight_checks.py` runs Django and Playwright readiness checks.
+- `scripts/test_run_tests.py` covers the command and preflight.
+- `scripts/test_preflight_checks.py` covers the readiness checks.
+- `scripts/test_runner_constants/` holds command names, messages, and limits.

package/.agents/skills/test-runner/scripts/preflight_checks.py

@@ -0,0 +1,365 @@
+"""Django and Playwright readiness checks for check_server_health, check_django_database,
+check_test_db_flag, check_runserver_port_conflicts, and build_frontend."""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Sequence
+from pathlib import Path
+from urllib.parse import urlparse
+
+from test_runner_constants.config.constants import (
+    ALL_BLOCKED_STATUS_CODES,
+    ALL_COLLECTSTATIC_ARGUMENTS,
+    ALL_FRONTEND_BUILD_ARGUMENTS,
+    ALL_LOCAL_SERVER_HOSTS,
+    ALL_PROCESS_INFORMATION_FIELDS,
+    ALL_RUNSERVER_OPTIONS_WITH_VALUES,
+    BUILD_TIMEOUT_SECONDS,
+    COMMAND_ARGUMENT_SEPARATOR,
+    CURL_EXECUTABLE_NAME,
+    CURL_MAX_TIME_FLAG,
+    CURL_OUTPUT_FLAG,
+    CURL_SILENT_FLAG,
+    CURL_STATUS_FORMAT,
+    CURL_WRITE_OUT_FLAG,
+    DEFAULT_DJANGO_PORT,
+    DIRECTORY_LIST_SEPARATOR,
+    DJANGO_DATABASE_FILENAME,
+    EXIT_CODE_SUCCESS,
+    FRONTEND_BUILD_FAILED_MESSAGE,
+    FRONTEND_DIRECTORY_NAME,
+    HEALTH_CHECK_ERROR_TEMPLATE,
+    HEALTH_CHECK_TIMEOUT_SECONDS,
+    MANAGE_PY_FILENAME,
+    MINIMUM_PROCESS_ARGUMENT_COUNT,
+    MINIMUM_RUNSERVER_PROCESS_COUNT,
+    MISSING_DATABASE_ERROR_TEMPLATE,
+    MISSING_TEST_DATABASE_FLAG_TEMPLATE,
+    NULL_DEVICE_PATH,
+    PORT_CONFLICT_ERROR_TEMPLATE,
+    PROCESS_CURL_TIMEOUT_SECONDS,
+    PROCESS_LIST_ARGUMENTS,
+    PROCESS_LIST_RUNSERVER_TOKEN,
+    PROCESS_LIST_SELF_FILTER_TOKEN,
+    RUNSERVER_COMMAND_INDEX,
+    RUNSERVER_COMMAND_NAME,
+    TEST_DATABASE_FLAG,
+    UNREACHABLE_ERROR_TEMPLATE,
+)
+
+try:
+    import psutil
+except ImportError:
+    psutil = None
+
+
+def check_server_health(target_url: str) -> str | None:
+    """Return a diagnostic when the target server is unavailable.
+
+    Args:
+        target_url: HTTP endpoint to request.
+
+    Returns:
+        A diagnostic string when the endpoint cannot serve tests, otherwise None.
+    """
+    try:
+        completed_process = subprocess.run(
+            _build_curl_arguments(target_url),
+            capture_output=True,
+            text=True,
+            timeout=HEALTH_CHECK_TIMEOUT_SECONDS,
+            check=False,
+        )
+        http_status_code = int(completed_process.stdout.strip())
+    except (OSError, ValueError, subprocess.TimeoutExpired):
+        return UNREACHABLE_ERROR_TEMPLATE.format(target_url)
+    return _server_health_error(target_url, http_status_code)
+
+
+def _build_curl_arguments(target_url: str) -> list[str]:
+    return [
+        CURL_EXECUTABLE_NAME,
+        CURL_SILENT_FLAG,
+        CURL_OUTPUT_FLAG,
+        NULL_DEVICE_PATH,
+        CURL_WRITE_OUT_FLAG,
+        CURL_STATUS_FORMAT,
+        CURL_MAX_TIME_FLAG,
+        str(PROCESS_CURL_TIMEOUT_SECONDS),
+        target_url,
+    ]
+
+
+def _server_health_error(target_url: str, http_status_code: int) -> str | None:
+    if http_status_code == EXIT_CODE_SUCCESS:
+        return UNREACHABLE_ERROR_TEMPLATE.format(target_url)
+    if http_status_code in ALL_BLOCKED_STATUS_CODES:
+        return HEALTH_CHECK_ERROR_TEMPLATE.format(
+            target_url, f"HTTP {http_status_code}"
+        )
+    return None
+
+
+def check_django_database(project_root: Path) -> str | None:
+    """Return a diagnostic when a Django database file is missing.
+
+    Args:
+        project_root: Django project directory to inspect.
+
+    Returns:
+        A diagnostic when manage.py exists without db.sqlite3, otherwise None.
+    """
+    manage_py_path = project_root / MANAGE_PY_FILENAME
+    if not manage_py_path.is_file():
+        return None
+    database_path = project_root / DJANGO_DATABASE_FILENAME
+    if database_path.is_file():
+        return None
+    return MISSING_DATABASE_ERROR_TEMPLATE.format(
+        DJANGO_DATABASE_FILENAME, project_root
+    )
+
+
+def extract_port_from_url(target_url: str) -> str:
+    """Return the URL port used by Django diagnostics.
+
+    Args:
+        target_url: URL whose authority may carry a port.
+
+    Returns:
+        The port in the URL, or the Django default when the URL has no valid port.
+    """
+    try:
+        parsed_url = urlparse(target_url)
+        if parsed_url.port is not None:
+            return str(parsed_url.port)
+    except ValueError:
+        return DEFAULT_DJANGO_PORT
+    return DEFAULT_DJANGO_PORT
+
+
+def check_test_db_flag(target_url: str, project_root: Path) -> str | None:
+    """Return a diagnostic when a detected runserver is missing `--test-db`.
+
+    Args:
+        target_url: URL that identifies the expected Django port.
+        project_root: Django project that owns the selected test run.
+
+    Returns:
+        A diagnostic when runserver is found without --test-db, otherwise None.
+    """
+    if not (project_root / MANAGE_PY_FILENAME).is_file():
+        return None
+    if (process_listing := _read_process_listing()) is None:
+        return None
+    target_port = extract_port_from_url(target_url)
+    is_runserver_found = False
+    for each_line in process_listing.splitlines():
+        if PROCESS_LIST_RUNSERVER_TOKEN not in each_line:
+            continue
+        if PROCESS_LIST_SELF_FILTER_TOKEN in each_line:
+            continue
+        runserver_arguments = _extract_runserver_arguments(each_line)
+        if not _runserver_uses_target_port(runserver_arguments, target_port):
+            continue
+        is_runserver_found = True
+        if TEST_DATABASE_FLAG in runserver_arguments:
+            return None
+    if not is_runserver_found:
+        return None
+    return MISSING_TEST_DATABASE_FLAG_TEMPLATE.format(target_port, target_port)
+
+
+def _extract_runserver_arguments(process_line: str) -> tuple[str, ...]:
+    all_process_tokens = tuple(process_line.split())
+    try:
+        runserver_index = all_process_tokens.index(RUNSERVER_COMMAND_NAME)
+    except ValueError:
+        return ()
+    return all_process_tokens[runserver_index + 1 :]
+
+
+def _runserver_uses_target_port(
+    all_runserver_arguments: Sequence[str], target_port: str
+) -> bool:
+    endpoint_argument = _find_runserver_endpoint_argument(all_runserver_arguments)
+    if endpoint_argument is None:
+        return target_port == DEFAULT_DJANGO_PORT
+    return endpoint_argument == target_port or endpoint_argument.endswith(
+        f":{target_port}"
+    )
+
+
+def _find_runserver_endpoint_argument(
+    all_runserver_arguments: Sequence[str],
+) -> str | None:
+    should_skip_next_argument = False
+    for each_argument in all_runserver_arguments:
+        if should_skip_next_argument:
+            should_skip_next_argument = False
+            continue
+        if each_argument in ALL_RUNSERVER_OPTIONS_WITH_VALUES:
+            should_skip_next_argument = True
+            continue
+        if not each_argument.startswith("-"):
+            return each_argument
+    return None
+
+
+def _read_process_listing() -> str | None:
+    try:
+        completed_process = subprocess.run(
+            list(PROCESS_LIST_ARGUMENTS),
+            capture_output=True,
+            text=True,
+            timeout=PROCESS_CURL_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    return completed_process.stdout or ""
+
+
+def _get_runserver_processes_on_port(
+    target_port: str,
+) -> list[tuple[int, str]]:
+    if psutil is None:
+        return []
+    all_runserver_processes: list[tuple[int, str]] = []
+    port_token = f":{target_port}"
+    for each_process in psutil.process_iter(ALL_PROCESS_INFORMATION_FIELDS):
+        process_record = _read_runserver_process(each_process, port_token)
+        if process_record is not None:
+            all_runserver_processes.append(process_record)
+    return all_runserver_processes
+
+
+def _read_runserver_process(
+    process: object,
+    port_token: str,
+) -> tuple[int, str] | None:
+    try:
+        process_information = getattr(process, "info", {})
+        if not isinstance(process_information, dict):
+            return None
+        commandline_parts = process_information.get("cmdline") or []
+        if len(commandline_parts) < MINIMUM_PROCESS_ARGUMENT_COUNT:
+            return None
+        if commandline_parts[1] != MANAGE_PY_FILENAME:
+            return None
+        if commandline_parts[RUNSERVER_COMMAND_INDEX] != RUNSERVER_COMMAND_NAME:
+            return None
+        if port_token not in COMMAND_ARGUMENT_SEPARATOR.join(commandline_parts):
+            return None
+        process_identifier = process_information.get("pid")
+        if not isinstance(process_identifier, int):
+            return None
+        return (process_identifier, process_information.get("cwd") or "")
+    except (
+        KeyError,
+        psutil.AccessDenied,
+        psutil.NoSuchProcess,
+        psutil.ZombieProcess,
+    ):
+        return None
+
+
+def check_runserver_port_conflicts(
+    target_url: str,
+    project_root: Path,
+) -> str | None:
+    """Return a diagnostic for cross-worktree runserver conflicts.
+
+    Args:
+        target_url: URL whose host and port identify the server.
+        project_root: Project directory running the test command.
+
+    Returns:
+        A diagnostic when separate worktrees share the port, otherwise None.
+    """
+    parsed_target_url = urlparse(target_url)
+    if (parsed_target_url.hostname or "") not in ALL_LOCAL_SERVER_HOSTS:
+        return None
+    target_port = str(parsed_target_url.port or DEFAULT_DJANGO_PORT)
+    all_processes = _get_runserver_processes_on_port(target_port)
+    all_directories = _unique_process_directories(all_processes)
+    if _has_no_process_conflict(all_processes, all_directories):
+        return None
+    return _build_conflict_message(target_port, project_root, all_directories)
+
+
+def _unique_process_directories(
+    all_processes: Sequence[tuple[int, str]],
+) -> set[str]:
+    return {
+        str(Path(each_directory).resolve())
+        for _, each_directory in all_processes
+        if each_directory
+    }
+
+
+def _has_no_process_conflict(
+    all_processes: Sequence[tuple[int, str]],
+    all_directories: set[str],
+) -> bool:
+    return (
+        len(all_processes) < MINIMUM_RUNSERVER_PROCESS_COUNT
+        or len(all_directories) < MINIMUM_RUNSERVER_PROCESS_COUNT
+    )
+
+
+def _build_conflict_message(
+    target_port: str,
+    project_root: Path,
+    all_directories: set[str],
+) -> str:
+    project_root_realpath = str(project_root.resolve())
+    all_other_worktrees = sorted(
+        each_directory
+        for each_directory in all_directories
+        if each_directory != project_root_realpath
+    )
+    all_conflicting_directories = all_other_worktrees or sorted(all_directories)
+    return PORT_CONFLICT_ERROR_TEMPLATE.format(
+        target_port, DIRECTORY_LIST_SEPARATOR.join(all_conflicting_directories)
+    )
+
+
+def build_frontend(project_root: Path) -> str | None:
+    """Build the frontend and collect Django static files when present.
+
+    Args:
+        project_root: Project directory containing the optional frontend.
+
+    Returns:
+        A diagnostic when either preparation step fails, otherwise None.
+    """
+    frontend_path = project_root / FRONTEND_DIRECTORY_NAME
+    if not frontend_path.is_dir():
+        return None
+    if _run_preparation(ALL_FRONTEND_BUILD_ARGUMENTS, frontend_path):
+        return FRONTEND_BUILD_FAILED_MESSAGE
+    if not (project_root / MANAGE_PY_FILENAME).is_file():
+        return None
+    if _run_preparation(ALL_COLLECTSTATIC_ARGUMENTS, project_root):
+        return FRONTEND_BUILD_FAILED_MESSAGE
+    return None
+
+
+def _run_preparation(
+    all_arguments: Sequence[str],
+    working_directory: Path,
+) -> bool:
+    try:
+        completed_process = subprocess.run(
+            list(all_arguments),
+            cwd=working_directory,
+            capture_output=True,
+            text=True,
+            timeout=BUILD_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return True
+    return completed_process.returncode != EXIT_CODE_SUCCESS