pestrail 0.1.0__tar.gz

pestrail-0.1.0/.env.example

@@ -0,0 +1,25 @@
+# Copy to your per-user pestrail config and fill in. Never commit it.
+#   Windows:       %APPDATA%\pestrail\.env
+#   macOS / Linux: ~/.config/pestrail/.env  (or $XDG_CONFIG_HOME/pestrail/.env)
+# A .env in the working directory is NOT loaded automatically; point PESTRAIL_ENV_FILE at it
+# to use one explicitly. Real environment variables (e.g. MCP client config) always win.
+# Only TESTRAIL_* and PESTRAIL_* keys are read from this file. If TESTRAIL_API_KEY is set in
+# the real environment, TESTRAIL_URL / TESTRAIL_CA_BUNDLE / TESTRAIL_ALLOW_HTTP must be set
+# there too (pestrail refuses to take them from this file).
+TESTRAIL_URL=https://your-company.testrail.io
+TESTRAIL_USERNAME=you@example.com
+TESTRAIL_API_KEY=your-api-key-here
+
+# Optional
+# TESTRAIL_READ_ONLY=true
+# Required for write mode (unless TESTRAIL_ALLOW_ANY_ATTACHMENT_PATH=true):
+# Separate multiple directories with ';' on Windows and ':' on macOS/Linux.
+TESTRAIL_ATTACHMENT_ROOTS=C:\Users\you\test-artifacts;D:\ci-logs
+# TESTRAIL_ALLOW_ANY_ATTACHMENT_PATH=true
+# Optional write-scope allowlists (comma-separated; prefixes OK: P1, R56):
+# TESTRAIL_ALLOWED_PROJECT_IDS=1,P3
+# TESTRAIL_ALLOWED_RUN_IDS=R56,78
+# TESTRAIL_TIMEOUT=30
+# TESTRAIL_UPLOAD_TIMEOUT=300
+# Only if your company's CA is not in the OS certificate store:
+# TESTRAIL_CA_BUNDLE=C:\certs\company-root-ca.pem

pestrail-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+.env
+.env.*
+!.env.example
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+.claude/
+.flake8
+# Local audit progress tracker (not committed)
+AUDIT_TODO.md

pestrail-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pestrail contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pestrail-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.5
+Name: pestrail
+Version: 0.1.0
+Summary: A safety-first MCP server for TestRail: browse projects, cases, runs and plans, add results and attachments. It cannot delete anything.
+Project-URL: Homepage, https://github.com/poyrazemun/pestrail
+Project-URL: Issues, https://github.com/poyrazemun/pestrail/issues
+Author: pestrail contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,mcp,model-context-protocol,qa,test-management,testrail
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: httpx<0.29,>=0.28
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: pydantic<3,>=2.14
+Requires-Dist: python-dotenv<2,>=1.0
+Requires-Dist: truststore<1,>=0.10
+Description-Content-Type: text/markdown
+
+# pestrail
+
+**A safety-first [MCP](https://modelcontextprotocol.io) server for TestRail.** Let Claude
+Desktop, Claude Code or any MCP client do everyday QA work in TestRail: browse projects,
+cases, runs and plans, read tests and results, **add results** and **attach files** (logs,
+screenshots, reports).
+
+**pestrail cannot delete anything**, cannot create, edit or move test cases, suites or
+sections, and cannot close runs or plans. These operations are missing by design and
+blocked in code, not just in prompts. Everything it writes is additive: new results and new
+attachments. See [docs/safety.md](https://github.com/poyrazemun/pestrail/blob/main/docs/safety.md).
+
+> Community project, **not affiliated with or endorsed by TestRail, Gurock Software or
+> Idera, Inc.** "TestRail" is a trademark of its respective owner.
+
+## Tools
+
+- **Read (29):** projects, suites, sections, cases, case/result fields, statuses, priorities,
+  configs, milestones, plans, runs, tests, results, attachment lists, users.
+- **Write (9, hidden in read-only mode):** `add_result`, `add_result_for_case`,
+  `add_results_for_cases` (report a whole test session in one call),
+  `add_result_with_attachments`, and `add_attachment_to_result` / `_run` / `_case` /
+  `_plan` / `_plan_entry`.
+
+IDs can be plain numbers or TestRail-style (`C1234`, `R56`, `T678`), and statuses can be
+given by name (`"Failed"`, custom statuses too).
+
+## Quick start
+
+1. **Get an API key.** A TestRail admin enables the API once (**Administration > Site
+   Settings > API**). Then go to **My Settings > API Keys > Add Key**. Prefer a dedicated
+   user with a role that can only view and add results.
+2. **Install [uv](https://docs.astral.sh/uv/getting-started/installation/).** pestrail isn't
+   on PyPI yet, so it runs from GitHub with `uvx --from git+https://github.com/poyrazemun/pestrail pestrail`.
+3. **Add it to your MCP client.** Start read-only and enable writes later.
+
+**Claude Desktop:** open **Settings > Desktop app > Extensions > Manage > Edit Config**, add the block below, then
+quit Claude Desktop completely and start it again.
+
+```json
+{
+  "mcpServers": {
+    "testrail": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/poyrazemun/pestrail", "pestrail"],
+      "env": {
+        "TESTRAIL_URL": "https://your-company.testrail.io",
+        "TESTRAIL_USERNAME": "you@your-company.com",
+        "TESTRAIL_API_KEY": "your-api-key",
+        "TESTRAIL_READ_ONLY": "true",
+        "PESTRAIL_ENV_FILE": "none"
+      }
+    }
+  }
+}
+```
+
+**Claude Code:**
+
+```bash
+claude mcp add testrail --scope user \
+  -e TESTRAIL_URL=https://your-company.testrail.io \
+  -e TESTRAIL_USERNAME=you@your-company.com \
+  -e TESTRAIL_API_KEY=your-api-key \
+  -e TESTRAIL_READ_ONLY=true \
+  -e PESTRAIL_ENV_FILE=none \
+  -- uvx --from git+https://github.com/poyrazemun/pestrail pestrail
+```
+
+(In PowerShell, end lines with a backtick `` ` `` instead of `\`.)
+
+**Enable writes:** remove `TESTRAIL_READ_ONLY` and set `TESTRAIL_ATTACHMENT_ROOTS` to the
+folders holding your test artifacts (`;`-separated on Windows, `:` on macOS/Linux). Write
+mode won't start without it. Optionally limit writes with `TESTRAIL_ALLOWED_PROJECT_IDS` /
+`TESTRAIL_ALLOWED_RUN_IDS`.
+
+## Key settings
+
+| Variable | Purpose |
+|---|---|
+| `TESTRAIL_URL`, `TESTRAIL_USERNAME`, `TESTRAIL_API_KEY` | Required. `https://` only. |
+| `TESTRAIL_READ_ONLY` | `true` registers only the read tools. |
+| `TESTRAIL_ATTACHMENT_ROOTS` | Folders attachments may be uploaded from. Required in write mode. |
+| `TESTRAIL_ALLOWED_PROJECT_IDS` / `TESTRAIL_ALLOWED_RUN_IDS` | Optional: confine writes to these projects/runs. |
+
+The full reference covers timeouts, `.env` files, proxies and corporate TLS:
+[docs/configuration.md](https://github.com/poyrazemun/pestrail/blob/main/docs/configuration.md).
+
+## Example prompts
+
+- *"In run R56, which tests are assigned to me? My TestRail email is me@your-company.com."*
+- *"Show me all Failed or Retest tests in run R56 with their latest comment."*
+- *"Report my session to run R56: C101 passed, C102 failed (defect UI-55), C103 blocked."*
+- *"Add a Failed result to C1234 in R56 and attach `C:\artifacts\login.log`."*
+
+Tip: ask the assistant to show you what it will add and wait for your OK. pestrail can't
+remove a result once it's added.
+
+## More
+
+- [Configuration](https://github.com/poyrazemun/pestrail/blob/main/docs/configuration.md): all settings, `.env` files, proxies/TLS, more
+  client examples
+- [Safety model and limits](https://github.com/poyrazemun/pestrail/blob/main/docs/safety.md)
+- [Troubleshooting](https://github.com/poyrazemun/pestrail/blob/main/docs/troubleshooting.md)
+- [Contributing](https://github.com/poyrazemun/pestrail/blob/main/CONTRIBUTING.md) · [Security policy](https://github.com/poyrazemun/pestrail/blob/main/SECURITY.md)
+
+## License
+
+[MIT](https://github.com/poyrazemun/pestrail/blob/main/LICENSE)

pestrail-0.1.0/README.md

@@ -0,0 +1,109 @@
+# pestrail
+
+**A safety-first [MCP](https://modelcontextprotocol.io) server for TestRail.** Let Claude
+Desktop, Claude Code or any MCP client do everyday QA work in TestRail: browse projects,
+cases, runs and plans, read tests and results, **add results** and **attach files** (logs,
+screenshots, reports).
+
+**pestrail cannot delete anything**, cannot create, edit or move test cases, suites or
+sections, and cannot close runs or plans. These operations are missing by design and
+blocked in code, not just in prompts. Everything it writes is additive: new results and new
+attachments. See [docs/safety.md](https://github.com/poyrazemun/pestrail/blob/main/docs/safety.md).
+
+> Community project, **not affiliated with or endorsed by TestRail, Gurock Software or
+> Idera, Inc.** "TestRail" is a trademark of its respective owner.
+
+## Tools
+
+- **Read (29):** projects, suites, sections, cases, case/result fields, statuses, priorities,
+  configs, milestones, plans, runs, tests, results, attachment lists, users.
+- **Write (9, hidden in read-only mode):** `add_result`, `add_result_for_case`,
+  `add_results_for_cases` (report a whole test session in one call),
+  `add_result_with_attachments`, and `add_attachment_to_result` / `_run` / `_case` /
+  `_plan` / `_plan_entry`.
+
+IDs can be plain numbers or TestRail-style (`C1234`, `R56`, `T678`), and statuses can be
+given by name (`"Failed"`, custom statuses too).
+
+## Quick start
+
+1. **Get an API key.** A TestRail admin enables the API once (**Administration > Site
+   Settings > API**). Then go to **My Settings > API Keys > Add Key**. Prefer a dedicated
+   user with a role that can only view and add results.
+2. **Install [uv](https://docs.astral.sh/uv/getting-started/installation/).** pestrail isn't
+   on PyPI yet, so it runs from GitHub with `uvx --from git+https://github.com/poyrazemun/pestrail pestrail`.
+3. **Add it to your MCP client.** Start read-only and enable writes later.
+
+**Claude Desktop:** open **Settings > Desktop app > Extensions > Manage > Edit Config**, add the block below, then
+quit Claude Desktop completely and start it again.
+
+```json
+{
+  "mcpServers": {
+    "testrail": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/poyrazemun/pestrail", "pestrail"],
+      "env": {
+        "TESTRAIL_URL": "https://your-company.testrail.io",
+        "TESTRAIL_USERNAME": "you@your-company.com",
+        "TESTRAIL_API_KEY": "your-api-key",
+        "TESTRAIL_READ_ONLY": "true",
+        "PESTRAIL_ENV_FILE": "none"
+      }
+    }
+  }
+}
+```
+
+**Claude Code:**
+
+```bash
+claude mcp add testrail --scope user \
+  -e TESTRAIL_URL=https://your-company.testrail.io \
+  -e TESTRAIL_USERNAME=you@your-company.com \
+  -e TESTRAIL_API_KEY=your-api-key \
+  -e TESTRAIL_READ_ONLY=true \
+  -e PESTRAIL_ENV_FILE=none \
+  -- uvx --from git+https://github.com/poyrazemun/pestrail pestrail
+```
+
+(In PowerShell, end lines with a backtick `` ` `` instead of `\`.)
+
+**Enable writes:** remove `TESTRAIL_READ_ONLY` and set `TESTRAIL_ATTACHMENT_ROOTS` to the
+folders holding your test artifacts (`;`-separated on Windows, `:` on macOS/Linux). Write
+mode won't start without it. Optionally limit writes with `TESTRAIL_ALLOWED_PROJECT_IDS` /
+`TESTRAIL_ALLOWED_RUN_IDS`.
+
+## Key settings
+
+| Variable | Purpose |
+|---|---|
+| `TESTRAIL_URL`, `TESTRAIL_USERNAME`, `TESTRAIL_API_KEY` | Required. `https://` only. |
+| `TESTRAIL_READ_ONLY` | `true` registers only the read tools. |
+| `TESTRAIL_ATTACHMENT_ROOTS` | Folders attachments may be uploaded from. Required in write mode. |
+| `TESTRAIL_ALLOWED_PROJECT_IDS` / `TESTRAIL_ALLOWED_RUN_IDS` | Optional: confine writes to these projects/runs. |
+
+The full reference covers timeouts, `.env` files, proxies and corporate TLS:
+[docs/configuration.md](https://github.com/poyrazemun/pestrail/blob/main/docs/configuration.md).
+
+## Example prompts
+
+- *"In run R56, which tests are assigned to me? My TestRail email is me@your-company.com."*
+- *"Show me all Failed or Retest tests in run R56 with their latest comment."*
+- *"Report my session to run R56: C101 passed, C102 failed (defect UI-55), C103 blocked."*
+- *"Add a Failed result to C1234 in R56 and attach `C:\artifacts\login.log`."*
+
+Tip: ask the assistant to show you what it will add and wait for your OK. pestrail can't
+remove a result once it's added.
+
+## More
+
+- [Configuration](https://github.com/poyrazemun/pestrail/blob/main/docs/configuration.md): all settings, `.env` files, proxies/TLS, more
+  client examples
+- [Safety model and limits](https://github.com/poyrazemun/pestrail/blob/main/docs/safety.md)
+- [Troubleshooting](https://github.com/poyrazemun/pestrail/blob/main/docs/troubleshooting.md)
+- [Contributing](https://github.com/poyrazemun/pestrail/blob/main/CONTRIBUTING.md) · [Security policy](https://github.com/poyrazemun/pestrail/blob/main/SECURITY.md)
+
+## License
+
+[MIT](https://github.com/poyrazemun/pestrail/blob/main/LICENSE)

pestrail-0.1.0/pyproject.toml

@@ -0,0 +1,73 @@
+[project]
+name = "pestrail"
+# Single source of truth: __version__ in src/pestrail/__init__.py (see [tool.hatch.version]).
+dynamic = ["version"]
+description = "A safety-first MCP server for TestRail: browse projects, cases, runs and plans, add results and attachments. It cannot delete anything."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "pestrail contributors" }]
+keywords = ["testrail", "mcp", "model-context-protocol", "qa", "test-management", "claude"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "mcp>=2.3,<3",
+    "httpx>=0.28,<0.29",
+    "pydantic>=2.14,<3",
+    "python-dotenv>=1.0,<2",
+    "truststore>=0.10,<1",
+]
+
+[project.scripts]
+pestrail = "pestrail.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/poyrazemun/pestrail"
+Issues = "https://github.com/poyrazemun/pestrail/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "respx>=0.21",
+    "ruff>=0.6",
+]
+
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/pestrail/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pestrail"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/pestrail", "tests", "README.md", "LICENSE", ".env.example", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "S", "SIM", "RUF"]
+ignore = []
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101", "S105", "S106", "S108"]

pestrail-0.1.0/src/pestrail/__init__.py

@@ -0,0 +1,3 @@
+"""pestrail: a safety-first MCP server for TestRail."""
+
+__version__ = "0.1.0"

pestrail-0.1.0/src/pestrail/__main__.py

@@ -0,0 +1,90 @@
+"""Entry point: ``pestrail`` / ``python -m pestrail`` runs the MCP server over stdio.
+
+stdout carries MCP protocol messages only; all diagnostics go to stderr.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import sys
+from pathlib import Path
+
+from . import __version__
+
+
+def _load_dotenv() -> None:
+    """Load the per-user .env file, or the one named by PESTRAIL_ENV_FILE.
+
+    See config.env_file_location for which file is used (never the working directory's
+    .env implicitly) and config.apply_env_file for the merge rules (real env wins, only
+    TESTRAIL_*/PESTRAIL_* keys, no destination settings from the file when the API key
+    comes from the environment).
+    """
+    from .config import ConfigError, apply_env_file, env_file_location
+
+    path, explicit = env_file_location()
+    if path is None:
+        return
+    if not path.is_file():
+        if explicit:
+            raise ConfigError(f"PESTRAIL_ENV_FILE not found: {path}")
+        return
+    from dotenv import dotenv_values
+
+    applied, ignored = apply_env_file(dotenv_values(path), os.environ)
+    log = logging.getLogger("pestrail")
+    if applied:
+        log.info("Loaded %s from %s", ", ".join(sorted(applied)), path)
+    if ignored:
+        log.warning("Ignored non-pestrail keys in %s: %s", path, ", ".join(sorted(ignored)))
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="pestrail", description="Safety-first MCP server for TestRail (stdio)."
+    )
+    parser.add_argument("--version", action="version", version=f"pestrail {__version__}")
+    parser.add_argument(
+        "--log-level",
+        default=os.environ.get("PESTRAIL_LOG_LEVEL", "WARNING"),
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+        help="Log level for stderr output (default: WARNING).",
+    )
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(
+        level=args.log_level,
+        stream=sys.stderr,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+    # httpx logs every request URL at INFO; keep that out of normal logs.
+    logging.getLogger("httpx").setLevel(max(logging.WARNING, logging.getLogger().level))
+
+    from .config import ConfigError, env_file_location, load_config
+
+    try:
+        _load_dotenv()
+        config = load_config()
+    except ConfigError as exc:
+        message = f"pestrail: configuration error: {exc}"
+        local_env = Path.cwd() / ".env"
+        if "Missing required" in str(exc) and local_env.is_file():
+            path, _ = env_file_location()
+            message += (
+                f"\npestrail: note: {local_env} exists but is not loaded automatically. "
+                "Set PESTRAIL_ENV_FILE to its path to use it"
+                + (f", or move it to {path}." if path else ".")
+            )
+        print(message, file=sys.stderr)
+        sys.exit(2)
+
+    from .server import create_server
+
+    server = create_server(config)
+    server.run("stdio")
+
+
+if __name__ == "__main__":
+    main()

pestrail-0.1.0/src/pestrail/attachments.py

@@ -0,0 +1,96 @@
+"""Local file validation for attachment uploads."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from .client import TestRailError
+
+#: TestRail's documented maximum attachment size.
+MAX_ATTACHMENT_BYTES = 256 * 1024 * 1024
+
+
+class AttachmentError(TestRailError):
+    """Raised when a local file may not be uploaded."""
+
+
+def validate_attachment_path(
+    raw_path: str,
+    roots: Sequence[Path],
+    *,
+    max_bytes: int = MAX_ATTACHMENT_BYTES,
+    allow_any_path: bool = False,
+) -> Path:
+    """Resolve ``raw_path`` and check it is an existing, allowed, not-too-large regular file.
+
+    * ``~`` is expanded.
+    * Relative paths are resolved against the attachment roots (the first root where the
+      file exists wins), never against the server's working directory, which MCP clients
+      set unpredictably. Without roots, relative paths are rejected.
+    * Symlinks and ``..`` are resolved *before* the root check, so a link inside a root that
+      points outside it is rejected.
+    * If ``roots`` is empty, uploads are refused unless ``allow_any_path`` is set (explicit
+      opt-in to uploading any readable file).
+    """
+    if not raw_path or not str(raw_path).strip():
+        raise AttachmentError("A file path is required.")
+    if "\x00" in raw_path:
+        raise AttachmentError("Invalid file path.")
+    if not roots and not allow_any_path:
+        raise AttachmentError(
+            "Uploads require TESTRAIL_ATTACHMENT_ROOTS (or "
+            "TESTRAIL_ALLOW_ANY_ATTACHMENT_PATH=true to allow any readable file)."
+        )
+
+    candidate = Path(str(raw_path).strip().strip('"')).expanduser()
+    if not candidate.is_absolute():
+        candidate = _resolve_relative(candidate, raw_path, roots)
+    try:
+        resolved = candidate.resolve(strict=True)
+    except FileNotFoundError as exc:
+        raise AttachmentError(f"File not found: {raw_path}") from exc
+    except (OSError, RuntimeError) as exc:
+        raise AttachmentError(f"Cannot access file {raw_path}: {type(exc).__name__}") from exc
+
+    if roots and not any(_is_within(resolved, root) for root in roots):
+        allowed = ", ".join(str(r) for r in roots)
+        raise AttachmentError(
+            f"File {raw_path} is outside the allowed attachment directories "
+            f"(TESTRAIL_ATTACHMENT_ROOTS): {allowed}"
+        )
+
+    if not resolved.is_file():
+        raise AttachmentError(f"Not a regular file: {raw_path}")
+
+    size = resolved.stat().st_size
+    if size > max_bytes:
+        raise AttachmentError(
+            f"File {resolved.name} is {size / 1024 / 1024:.1f} MB; "
+            f"TestRail's limit is {max_bytes // 1024 // 1024} MB."
+        )
+    return resolved
+
+
+def _resolve_relative(candidate: Path, raw_path: str, roots: Sequence[Path]) -> Path:
+    if not roots:
+        raise AttachmentError(
+            f"Relative path {raw_path!r} is not supported: use an absolute path "
+            "(or set TESTRAIL_ATTACHMENT_ROOTS so relative paths are resolved against it)."
+        )
+    for root in roots:
+        joined = root / candidate
+        if joined.exists():
+            return joined
+    searched = ", ".join(str(r) for r in roots)
+    raise AttachmentError(f"File not found: {raw_path} (searched in: {searched})")
+
+
+def _is_within(path: Path, root: Path) -> bool:
+    try:
+        root_resolved = root.resolve(strict=True)
+    except (OSError, RuntimeError):
+        return False
+    # is_relative_to compares whole path parts, so "/data/logs2" is not inside "/data/logs".
+    # WindowsPath comparisons are case-insensitive, matching NTFS semantics.
+    return path.is_relative_to(root_resolved)