runspec-gitlab-core 0.1.0__tar.gz

runspec_gitlab_core-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+env/
+.env
+pip-wheel-metadata/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml
+*.cover
+
+# Node
+node_modules/
+dist/
+*.js.map
+.npm
+
+# Go
+*.exe
+*.test
+*.out
+vendor/
+
+# IDE
+.idea/
+.vscode/
+*.iml
+*.iws
+*.ipr
+.DS_Store
+Thumbs.db
+
+# Docs
+site/
+
+# Misc
+*.log
+*.tmp
+
+# External reference repos (cloned locally, not committed)
+chainlit-docs/
+.chainlit/
+
+# Claude Code local config (machine-specific)
+.claude/launch.json
+
+# Stray committed test venv (removed from tracking)
+.venv-test/

runspec_gitlab_core-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to `runspec-gitlab-core` are documented here.
+
+## [0.1.0]
+
+Initial release. Pure-Python GitLab REST (v4) read helpers — the importable core
+behind `runspec-gitlab`, with **no runspec dependency, no runspec.toml, and no
+entry points** (so it surfaces no runnables and stays importable on its own).
+
+- `GitlabConfig` + `config_from_env` — env-var driven connection/identity
+  (`GITLAB_URL` defaulting to `https://gitlab.com`, `GITLAB_TOKEN`, optional
+  `GITLAB_PROJECT`), with `GITLAB_<ENV>_*` prefixes selected by `env`.
+- `gitlab_request` / `encode_project` — authenticated `PRIVATE-TOKEN` request
+  helper against `{base_url}/api/v4`, raising `GitlabError` on non-2xx.
+- Read helpers ported from the read tools of GitLab's hosted MCP server:
+  `whoami`, `get_project`, `search_projects`, `list_issues`, `get_issue`,
+  `list_merge_requests`, `get_merge_request`, `get_merge_request_changes`,
+  `list_pipelines`, `get_pipeline_jobs`, `get_job_log`, `get_file`, `list_tree`.

runspec_gitlab_core-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: runspec-gitlab-core
+Version: 0.1.0
+Summary: Pure-Python GitLab REST helpers — the importable core behind runspec-gitlab (no runspec dependency, no runnables)
+Requires-Python: >=3.10
+Requires-Dist: httpx
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff==0.15.20; extra == 'dev'

runspec_gitlab_core-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runspec-gitlab-core"
+version = "0.1.0"
+requires-python = ">=3.10"
+description = "Pure-Python GitLab REST helpers — the importable core behind runspec-gitlab (no runspec dependency, no runnables)"
+dependencies = [
+    "httpx",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff==0.15.20",
+    "mypy",
+    "pytest>=8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+
+[tool.ruff]
+line-length = 200
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

runspec_gitlab_core-0.1.0/runspec_gitlab_core/__init__.py

@@ -0,0 +1,63 @@
+"""runspec-gitlab-core — pure-Python GitLab REST (v4) read helpers.
+
+This package depends only on ``httpx`` — it has **no dependency on runspec** and
+ships **no runspec.toml and no entry points**, so installing it exposes the
+helper functions for import without surfacing any runnables (it is invisible to
+``runspec local`` / ``runspec serve`` discovery). ``runspec-gitlab`` depends on it
+and wraps each helper as a verb of the ``gitlab`` runnable.
+
+The helpers port the read tools of GitLab's own (hosted) MCP server onto the
+public REST API. Every operation takes an explicit :class:`GitlabConfig` first
+argument, so a private (e.g. Nexus-hosted) wrapper package can inject credentials
+in code, bake in a default ``project`` / ``env``, and build "one runnable per
+project" on top without re-implementing the REST plumbing. Each function does the
+work and returns plain data; failures raise :class:`GitlabError`.
+"""
+
+from runspec_gitlab_core.client import (
+    DEFAULT_URL,
+    VALID_ENVS,
+    GitlabConfig,
+    GitlabError,
+    config_from_env,
+    encode_project,
+    gitlab_request,
+)
+from runspec_gitlab_core.issues import get_issue, list_issues
+from runspec_gitlab_core.merge_requests import (
+    get_merge_request,
+    get_merge_request_changes,
+    list_merge_requests,
+)
+from runspec_gitlab_core.pipelines import get_job_log, get_pipeline_jobs, list_pipelines
+from runspec_gitlab_core.projects import get_project, search_projects, whoami
+from runspec_gitlab_core.repository import get_file, list_tree
+
+__all__ = [
+    # client / config
+    "GitlabConfig",
+    "GitlabError",
+    "config_from_env",
+    "gitlab_request",
+    "encode_project",
+    "VALID_ENVS",
+    "DEFAULT_URL",
+    # identity / projects
+    "whoami",
+    "get_project",
+    "search_projects",
+    # issues
+    "list_issues",
+    "get_issue",
+    # merge requests
+    "list_merge_requests",
+    "get_merge_request",
+    "get_merge_request_changes",
+    # pipelines / jobs
+    "list_pipelines",
+    "get_pipeline_jobs",
+    "get_job_log",
+    # repository
+    "get_file",
+    "list_tree",
+]

runspec_gitlab_core-0.1.0/runspec_gitlab_core/client.py

@@ -0,0 +1,171 @@
+"""client.py — authenticated GitLab REST (v4) helper.
+
+This module is the reusable core of ``runspec-gitlab``. Every operation function
+in the package takes an explicit :class:`GitlabConfig` as its first argument, so a
+private (e.g. Nexus-hosted) wrapper package can construct a config from injected
+credentials and call the same functions the CLI runnable's verbs call.
+
+Auth is environment-variable driven (see :func:`config_from_env`) but a caller is
+free to build a :class:`GitlabConfig` by hand. A single personal-access token
+(``GITLAB_TOKEN``) is sent as the ``PRIVATE-TOKEN`` header; the instance URL
+(``GITLAB_URL``) defaults to ``https://gitlab.com`` for the SaaS case.
+
+This mirrors the read tools of GitLab's own (hosted) MCP server, but ports them
+onto the public REST API rather than proxying that server — so the runnable runs
+over the runspec-console SSH fleet with no extra process.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+VALID_ENVS = ("dev", "uat", "prod")
+DEFAULT_URL = "https://gitlab.com"
+
+
+class GitlabError(Exception):
+    """Raised on configuration problems and non-2xx API responses."""
+
+
+@dataclass
+class GitlabConfig:
+    """Connection + identity for a GitLab instance.
+
+    ``project`` is an optional default a wrapper package can bake in once so
+    every call inherits it (accepts a numeric id or a ``namespace/project``
+    path). ``env`` records which logical environment (dev/uat/prod) the config
+    targets, when one was selected.
+    """
+
+    base_url: str
+    token: str
+    project: str | None = None
+    env: str | None = None
+
+
+def _env_first(names: list[str]) -> str | None:
+    """Return the first non-empty environment variable among ``names``."""
+    for name in names:
+        value = os.environ.get(name)
+        if value:
+            return value
+    return None
+
+
+def config_from_env(env: str | None = None) -> GitlabConfig:
+    """Build a :class:`GitlabConfig` from environment variables.
+
+    When ``env`` (or the ``GITLAB_ENV`` variable) selects dev/uat/prod, the
+    environment-prefixed variables are read first (e.g. ``GITLAB_UAT_TOKEN``),
+    falling back to the unprefixed ``GITLAB_*`` family for single-instance
+    setups. ``GITLAB_URL`` defaults to ``https://gitlab.com`` when unset. Raises
+    :class:`GitlabError` with an actionable message when the env label is invalid
+    or the token is missing.
+    """
+    env = env or os.environ.get("GITLAB_ENV")
+    if env is not None:
+        env = env.lower()
+        if env not in VALID_ENVS:
+            raise GitlabError(f"Invalid env {env!r} — expected one of {', '.join(VALID_ENVS)}")
+
+    def lookup(suffix: str) -> str | None:
+        names = []
+        if env:
+            names.append(f"GITLAB_{env.upper()}_{suffix}")
+        names.append(f"GITLAB_{suffix}")
+        return _env_first(names)
+
+    token = lookup("TOKEN")
+    if not token:
+        hint = f"GITLAB_{env.upper()}_TOKEN" if env else "GITLAB_TOKEN"
+        raise GitlabError(f"No token configured — set {hint} (a GitLab personal access token)")
+
+    base_url = lookup("URL") or DEFAULT_URL
+
+    return GitlabConfig(
+        base_url=base_url.rstrip("/"),
+        token=token,
+        project=lookup("PROJECT"),
+        env=env,
+    )
+
+
+def encode_project(project: str) -> str:
+    """URL-encode a project identifier for the ``/projects/:id`` path.
+
+    A ``namespace/project`` path is percent-encoded (slashes included, as GitLab
+    requires); a numeric id passes through unchanged.
+    """
+    return quote(str(project), safe="")
+
+
+def gitlab_request(
+    method: str,
+    path: str,
+    *,
+    config: GitlabConfig,
+    params: dict[str, Any] | None = None,
+    raw: bool = False,
+    timeout: int = 30,
+) -> Any:
+    """Make an authenticated request against ``{base_url}/api/v4`` and return the
+    parsed JSON body (or the raw text when ``raw=True`` — used for job traces).
+
+    ``path`` should start with ``/`` (e.g. ``/projects/1/issues``). ``None`` values
+    in ``params`` are dropped and booleans are rendered as ``"true"``/``"false"``.
+    Raises :class:`GitlabError` on any non-2xx response, surfacing the server's
+    error message.
+    """
+    headers = {"PRIVATE-TOKEN": config.token}
+    if not raw:
+        headers["Accept"] = "application/json"
+
+    clean: dict[str, Any] | None = None
+    if params:
+        clean = {}
+        for key, value in params.items():
+            if value is None:
+                continue
+            clean[key] = "true" if value is True else "false" if value is False else value
+
+    resp = httpx.request(
+        method,
+        f"{config.base_url}/api/v4{path}",
+        headers=headers,
+        params=clean,
+        timeout=timeout,
+    )
+    if resp.status_code >= 400:
+        raise GitlabError(_error_message(resp))
+    if resp.status_code == 204 or not resp.content:
+        return "" if raw else None
+    if raw:
+        return resp.text
+    return resp.json()
+
+
+def _error_message(resp: httpx.Response) -> str:
+    """Extract a human-readable message from a GitLab error response body."""
+    try:
+        body = resp.json()
+    except Exception:
+        return f"GitLab {resp.status_code}: {resp.text[:500]}"
+
+    if isinstance(body, dict):
+        # GitLab returns {"message": "..."} or {"message": {field: [errs]}},
+        # and OAuth-style {"error": "...", "error_description": "..."}.
+        message = body.get("message")
+        if isinstance(message, str):
+            return f"GitLab {resp.status_code}: {message}"
+        if isinstance(message, dict):
+            parts = [f"{k}: {', '.join(map(str, v)) if isinstance(v, list) else v}" for k, v in message.items()]
+            return f"GitLab {resp.status_code}: {'; '.join(parts)}"
+        error = body.get("error_description") or body.get("error")
+        if error:
+            return f"GitLab {resp.status_code}: {error}"
+    return f"GitLab {resp.status_code}: {str(body)[:500]}"

runspec_gitlab_core-0.1.0/runspec_gitlab_core/issues.py

@@ -0,0 +1,45 @@
+"""issues.py — project issue read operations (GitLab REST v4)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runspec_gitlab_core.client import GitlabConfig, gitlab_request
+from runspec_gitlab_core.projects import _project
+
+
+def list_issues(
+    config: GitlabConfig,
+    project: str | None = None,
+    state: str | None = None,
+    labels: str | None = None,
+    search: str | None = None,
+    per_page: int = 20,
+    page: int = 1,
+) -> list[dict[str, Any]]:
+    """List a project's issues.
+
+    ``state`` is ``opened``/``closed``/``all``; ``labels`` is a comma-separated
+    label list; ``search`` matches title/description.
+    """
+    return gitlab_request(
+        "GET",
+        f"/projects/{_project(config, project)}/issues",
+        config=config,
+        params={
+            "state": state,
+            "labels": labels,
+            "search": search,
+            "per_page": per_page,
+            "page": page,
+        },
+    )
+
+
+def get_issue(config: GitlabConfig, issue_iid: int, project: str | None = None) -> dict[str, Any]:
+    """Fetch a single issue by its project-scoped internal id (``iid``)."""
+    return gitlab_request(
+        "GET",
+        f"/projects/{_project(config, project)}/issues/{issue_iid}",
+        config=config,
+    )

runspec_gitlab_core-0.1.0/runspec_gitlab_core/merge_requests.py

@@ -0,0 +1,45 @@
+"""merge_requests.py — merge-request read operations (GitLab REST v4)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runspec_gitlab_core.client import GitlabConfig, gitlab_request
+from runspec_gitlab_core.projects import _project
+
+
+def list_merge_requests(
+    config: GitlabConfig,
+    project: str | None = None,
+    state: str | None = None,
+    per_page: int = 20,
+    page: int = 1,
+) -> list[dict[str, Any]]:
+    """List a project's merge requests.
+
+    ``state`` is ``opened``/``closed``/``merged``/``locked``/``all``.
+    """
+    return gitlab_request(
+        "GET",
+        f"/projects/{_project(config, project)}/merge_requests",
+        config=config,
+        params={"state": state, "per_page": per_page, "page": page},
+    )
+
+
+def get_merge_request(config: GitlabConfig, mr_iid: int, project: str | None = None) -> dict[str, Any]:
+    """Fetch a single merge request by its project-scoped internal id (``iid``)."""
+    return gitlab_request(
+        "GET",
+        f"/projects/{_project(config, project)}/merge_requests/{mr_iid}",
+        config=config,
+    )
+
+
+def get_merge_request_changes(config: GitlabConfig, mr_iid: int, project: str | None = None) -> dict[str, Any]:
+    """Fetch a merge request together with its file changes / diffs."""
+    return gitlab_request(
+        "GET",
+        f"/projects/{_project(config, project)}/merge_requests/{mr_iid}/changes",
+        config=config,
+    )

runspec_gitlab_core-0.1.0/runspec_gitlab_core/pipelines.py

@@ -0,0 +1,68 @@
+"""pipelines.py — CI/CD pipeline + job read operations (GitLab REST v4)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runspec_gitlab_core.client import GitlabConfig, gitlab_request
+from runspec_gitlab_core.projects import _project
+
+
+def list_pipelines(
+    config: GitlabConfig,
+    project: str | None = None,
+    ref: str | None = None,
+    status: str | None = None,
+    per_page: int = 20,
+    page: int = 1,
+) -> list[dict[str, Any]]:
+    """List a project's pipelines, optionally filtered by ``ref`` (branch/tag)
+    and ``status`` (e.g. ``success``/``failed``/``running``)."""
+    return gitlab_request(
+        "GET",
+        f"/projects/{_project(config, project)}/pipelines",
+        config=config,
+        params={"ref": ref, "status": status, "per_page": per_page, "page": page},
+    )
+
+
+def get_pipeline_jobs(
+    config: GitlabConfig,
+    pipeline_id: int,
+    project: str | None = None,
+    per_page: int = 20,
+    page: int = 1,
+) -> list[dict[str, Any]]:
+    """List the jobs of a pipeline (by pipeline id)."""
+    return gitlab_request(
+        "GET",
+        f"/projects/{_project(config, project)}/pipelines/{pipeline_id}/jobs",
+        config=config,
+        params={"per_page": per_page, "page": page},
+    )
+
+
+def get_job_log(
+    config: GitlabConfig,
+    job_id: int,
+    project: str | None = None,
+    tail: int | None = None,
+) -> dict[str, Any]:
+    """Fetch a job's log (trace) as plain text.
+
+    ``tail`` returns only the last N lines — logs are large, so an agent should
+    usually pass one. Returns ``{job_id, trace, truncated}``.
+    """
+    text = gitlab_request(
+        "GET",
+        f"/projects/{_project(config, project)}/jobs/{job_id}/trace",
+        config=config,
+        raw=True,
+    )
+    truncated = False
+    if tail is not None and tail >= 0:
+        lines = text.splitlines()
+        if len(lines) > tail:
+            text = "\n".join(lines[-tail:])
+            truncated = True
+    return {"job_id": job_id, "trace": text, "truncated": truncated}

runspec_gitlab_core-0.1.0/runspec_gitlab_core/projects.py

@@ -0,0 +1,51 @@
+"""projects.py — identity + project read operations (GitLab REST v4)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runspec_gitlab_core.client import GitlabConfig, GitlabError, encode_project, gitlab_request
+
+
+def _project(config: GitlabConfig, project: str | None) -> str:
+    """Resolve the target project, falling back to the config default, and
+    percent-encode it for the URL path."""
+    target = project or config.project
+    if not target:
+        raise GitlabError("No project — pass project or set it on the config (GITLAB_PROJECT)")
+    return encode_project(target)
+
+
+def whoami(config: GitlabConfig) -> dict[str, Any]:
+    """Return the authenticated user (``GET /user``) — a quick token/identity check."""
+    return gitlab_request("GET", "/user", config=config)
+
+
+def get_project(config: GitlabConfig, project: str | None = None) -> dict[str, Any]:
+    """Fetch a single project's metadata by numeric id or ``namespace/project`` path."""
+    return gitlab_request("GET", f"/projects/{_project(config, project)}", config=config)
+
+
+def search_projects(
+    config: GitlabConfig,
+    search: str,
+    membership: bool = False,
+    per_page: int = 20,
+    page: int = 1,
+) -> list[dict[str, Any]]:
+    """Search visible projects by name/path.
+
+    ``membership`` limits results to projects the token's user is a member of.
+    """
+    return gitlab_request(
+        "GET",
+        "/projects",
+        config=config,
+        params={
+            "search": search,
+            "membership": membership,
+            "order_by": "last_activity_at",
+            "per_page": per_page,
+            "page": page,
+        },
+    )

runspec_gitlab_core-0.1.0/runspec_gitlab_core/repository.py

@@ -0,0 +1,68 @@
+"""repository.py — repository file + tree read operations (GitLab REST v4)."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+from typing import Any
+from urllib.parse import quote
+
+from runspec_gitlab_core.client import GitlabConfig, gitlab_request
+from runspec_gitlab_core.projects import _project
+
+
+def get_file(
+    config: GitlabConfig,
+    file_path: str,
+    ref: str = "HEAD",
+    project: str | None = None,
+) -> dict[str, Any]:
+    """Fetch a single repository file at ``ref`` (default ``HEAD`` = the default
+    branch's tip).
+
+    The base64 payload GitLab returns is decoded: UTF-8 text is returned under
+    ``content``; a file that isn't valid UTF-8 is reported as
+    ``{"binary": true, "content_base64": ...}`` instead.
+    """
+    encoded_path = quote(file_path, safe="")
+    result = gitlab_request(
+        "GET",
+        f"/projects/{_project(config, project)}/repository/files/{encoded_path}",
+        config=config,
+        params={"ref": ref},
+    )
+    raw = result.get("content")
+    if isinstance(raw, str) and result.get("encoding") == "base64":
+        try:
+            data = base64.b64decode(raw)
+            result["content"] = data.decode("utf-8")
+        except (binascii.Error, UnicodeDecodeError):
+            result.pop("content", None)
+            result["content_base64"] = raw
+            result["binary"] = True
+    return result
+
+
+def list_tree(
+    config: GitlabConfig,
+    path: str | None = None,
+    ref: str | None = None,
+    recursive: bool = False,
+    project: str | None = None,
+    per_page: int = 20,
+    page: int = 1,
+) -> list[dict[str, Any]]:
+    """List a repository tree at ``path`` (default root) and ``ref`` (default
+    branch). ``recursive`` walks subdirectories."""
+    return gitlab_request(
+        "GET",
+        f"/projects/{_project(config, project)}/repository/tree",
+        config=config,
+        params={
+            "path": path,
+            "ref": ref,
+            "recursive": recursive,
+            "per_page": per_page,
+            "page": page,
+        },
+    )

runspec_gitlab_core-0.1.0/tests/conftest.py

@@ -0,0 +1,33 @@
+"""Shared test helpers: a clean GITLAB_* env and an httpx.MockTransport router."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import httpx
+import pytest
+
+from runspec_gitlab_core import client as client_mod
+
+_SUFFIXES = ("URL", "TOKEN", "PROJECT")
+_ALL_VARS = ["GITLAB_ENV"] + [f"GITLAB_{s}" for s in _SUFFIXES]
+for _env in ("DEV", "UAT", "PROD"):
+    _ALL_VARS += [f"GITLAB_{_env}_{s}" for s in _SUFFIXES]
+
+
+@pytest.fixture(autouse=True)
+def _clean_env(monkeypatch):
+    for var in _ALL_VARS:
+        monkeypatch.delenv(var, raising=False)
+
+
+def mock_request(monkeypatch, handler: Callable[[httpx.Request], httpx.Response]) -> None:
+    """Route runspec_gitlab_core.client's module-level httpx.request through a
+    MockTransport so tests exercise real URL/param/header building."""
+    transport = httpx.MockTransport(handler)
+
+    def fake_request(method, url, **kwargs):
+        with httpx.Client(transport=transport) as c:
+            return c.request(method, url, **kwargs)
+
+    monkeypatch.setattr(client_mod.httpx, "request", fake_request)

runspec_gitlab_core-0.1.0/tests/test_api.py

@@ -0,0 +1,138 @@
+"""Read-helper tests — assert each helper hits the right URL/params and shapes
+its result, routed through an httpx.MockTransport (no real network)."""
+
+import base64
+
+import httpx
+import pytest
+
+from runspec_gitlab_core import (
+    GitlabConfig,
+    GitlabError,
+    get_file,
+    get_issue,
+    get_job_log,
+    get_merge_request_changes,
+    list_issues,
+    list_pipelines,
+    list_tree,
+    search_projects,
+    whoami,
+)
+from tests.conftest import mock_request
+
+CFG = GitlabConfig(base_url="https://gl", token="tok", project="grp/app")
+
+
+def _capture(monkeypatch, response: httpx.Response) -> dict:
+    seen: dict = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        # raw_path keeps %2F encoded (the real wire path); .path would decode it.
+        seen["path"] = request.url.raw_path.decode().split("?")[0]
+        seen["query"] = dict(request.url.params)
+        return response
+
+    mock_request(monkeypatch, handler)
+    return seen
+
+
+def test_whoami(monkeypatch):
+    seen = _capture(monkeypatch, httpx.Response(200, json={"username": "alice"}))
+    assert whoami(CFG) == {"username": "alice"}
+    assert seen["path"] == "/api/v4/user"
+
+
+def test_search_projects_encodes_membership(monkeypatch):
+    seen = _capture(monkeypatch, httpx.Response(200, json=[]))
+    search_projects(CFG, "runspec", membership=True)
+    assert seen["path"] == "/api/v4/projects"
+    assert seen["query"]["search"] == "runspec"
+    assert seen["query"]["membership"] == "true"
+
+
+def test_list_issues_uses_default_project_and_filters(monkeypatch):
+    seen = _capture(monkeypatch, httpx.Response(200, json=[{"iid": 1}]))
+    list_issues(CFG, state="opened", labels="bug,urgent")
+    assert seen["path"] == "/api/v4/projects/grp%2Fapp/issues"
+    assert seen["query"]["state"] == "opened"
+    assert seen["query"]["labels"] == "bug,urgent"
+
+
+def test_get_issue_by_iid(monkeypatch):
+    seen = _capture(monkeypatch, httpx.Response(200, json={"iid": 5}))
+    assert get_issue(CFG, 5) == {"iid": 5}
+    assert seen["path"] == "/api/v4/projects/grp%2Fapp/issues/5"
+
+
+def test_explicit_project_overrides_default(monkeypatch):
+    seen = _capture(monkeypatch, httpx.Response(200, json=[]))
+    list_issues(CFG, project="99")
+    assert seen["path"] == "/api/v4/projects/99/issues"
+
+
+def test_missing_project_raises(monkeypatch):
+    _capture(monkeypatch, httpx.Response(200, json=[]))
+    cfg = GitlabConfig(base_url="https://gl", token="tok")  # no default project
+    with pytest.raises(GitlabError, match="No project"):
+        list_issues(cfg)
+
+
+def test_mr_changes_path(monkeypatch):
+    seen = _capture(monkeypatch, httpx.Response(200, json={"changes": []}))
+    get_merge_request_changes(CFG, 12)
+    assert seen["path"] == "/api/v4/projects/grp%2Fapp/merge_requests/12/changes"
+
+
+def test_list_pipelines_filters(monkeypatch):
+    seen = _capture(monkeypatch, httpx.Response(200, json=[]))
+    list_pipelines(CFG, ref="main", status="failed")
+    assert seen["path"] == "/api/v4/projects/grp%2Fapp/pipelines"
+    assert seen["query"]["ref"] == "main"
+    assert seen["query"]["status"] == "failed"
+
+
+def test_get_job_log_tails(monkeypatch):
+    body = "\n".join(f"line{i}" for i in range(10))
+    seen = _capture(monkeypatch, httpx.Response(200, text=body))
+    result = get_job_log(CFG, 77, tail=3)
+    assert seen["path"] == "/api/v4/projects/grp%2Fapp/jobs/77/trace"
+    assert result["job_id"] == 77
+    assert result["truncated"] is True
+    assert result["trace"] == "line7\nline8\nline9"
+
+
+def test_get_job_log_no_tail_not_truncated(monkeypatch):
+    _capture(monkeypatch, httpx.Response(200, text="a\nb"))
+    result = get_job_log(CFG, 1)
+    assert result["truncated"] is False
+    assert result["trace"] == "a\nb"
+
+
+def test_get_file_decodes_base64_text(monkeypatch):
+    encoded = base64.b64encode(b"hello world").decode()
+    seen = _capture(
+        monkeypatch,
+        httpx.Response(200, json={"file_path": "README.md", "encoding": "base64", "content": encoded}),
+    )
+    result = get_file(CFG, "docs/README.md", ref="main")
+    assert seen["path"] == "/api/v4/projects/grp%2Fapp/repository/files/docs%2FREADME.md"
+    assert seen["query"]["ref"] == "main"
+    assert result["content"] == "hello world"
+
+
+def test_get_file_flags_binary(monkeypatch):
+    encoded = base64.b64encode(b"\xff\xfe\x00\x01").decode()
+    _capture(monkeypatch, httpx.Response(200, json={"encoding": "base64", "content": encoded}))
+    result = get_file(CFG, "logo.png")
+    assert result.get("binary") is True
+    assert result["content_base64"] == encoded
+    assert "content" not in result
+
+
+def test_list_tree_recursive(monkeypatch):
+    seen = _capture(monkeypatch, httpx.Response(200, json=[{"name": "src"}]))
+    list_tree(CFG, path="src", ref="main", recursive=True)
+    assert seen["path"] == "/api/v4/projects/grp%2Fapp/repository/tree"
+    assert seen["query"]["recursive"] == "true"
+    assert seen["query"]["path"] == "src"

runspec_gitlab_core-0.1.0/tests/test_client.py

@@ -0,0 +1,145 @@
+import httpx
+import pytest
+
+from runspec_gitlab_core.client import (
+    DEFAULT_URL,
+    GitlabConfig,
+    GitlabError,
+    config_from_env,
+    encode_project,
+    gitlab_request,
+)
+from tests.conftest import mock_request
+
+# ── config_from_env ─────────────────────────────────────────────────────────
+
+
+def test_config_from_env_defaults_url(monkeypatch):
+    monkeypatch.setenv("GITLAB_TOKEN", "tok123")
+    cfg = config_from_env()
+    assert cfg.base_url == DEFAULT_URL
+    assert cfg.token == "tok123"
+    assert cfg.env is None
+
+
+def test_config_from_env_strips_trailing_slash(monkeypatch):
+    monkeypatch.setenv("GITLAB_TOKEN", "tok")
+    monkeypatch.setenv("GITLAB_URL", "https://gitlab.example.com/")
+    assert config_from_env().base_url == "https://gitlab.example.com"
+
+
+def test_env_prefixed_resolution(monkeypatch):
+    monkeypatch.setenv("GITLAB_UAT_URL", "https://uat.example.com")
+    monkeypatch.setenv("GITLAB_UAT_TOKEN", "uat-tok")
+    monkeypatch.setenv("GITLAB_UAT_PROJECT", "grp/app")
+    cfg = config_from_env(env="uat")
+    assert cfg.base_url == "https://uat.example.com"
+    assert cfg.token == "uat-tok"
+    assert cfg.project == "grp/app"
+    assert cfg.env == "uat"
+
+
+def test_env_prefixed_falls_back_to_unprefixed(monkeypatch):
+    monkeypatch.setenv("GITLAB_PROD_URL", "https://prod.example.com")
+    monkeypatch.setenv("GITLAB_TOKEN", "shared-tok")
+    cfg = config_from_env(env="prod")
+    assert cfg.base_url == "https://prod.example.com"
+    assert cfg.token == "shared-tok"
+
+
+def test_env_from_gitlab_env_var(monkeypatch):
+    monkeypatch.setenv("GITLAB_ENV", "dev")
+    monkeypatch.setenv("GITLAB_DEV_TOKEN", "dev-tok")
+    cfg = config_from_env()
+    assert cfg.env == "dev"
+    assert cfg.token == "dev-tok"
+
+
+def test_invalid_env_raises(monkeypatch):
+    with pytest.raises(GitlabError, match="Invalid env"):
+        config_from_env(env="staging")
+
+
+def test_missing_token_raises(monkeypatch):
+    with pytest.raises(GitlabError, match="No token"):
+        config_from_env()
+
+
+# ── encode_project ──────────────────────────────────────────────────────────
+
+
+def test_encode_project_path():
+    assert encode_project("group/sub/app") == "group%2Fsub%2Fapp"
+
+
+def test_encode_project_numeric():
+    assert encode_project("42") == "42"
+
+
+# ── gitlab_request ──────────────────────────────────────────────────────────
+
+
+def test_gitlab_request_builds_url_auth_and_params(monkeypatch):
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["url"] = str(request.url)
+        seen["method"] = request.method
+        seen["token"] = request.headers.get("PRIVATE-TOKEN")
+        return httpx.Response(200, json=[{"id": 1}])
+
+    mock_request(monkeypatch, handler)
+    cfg = GitlabConfig(base_url="https://gitlab.example.com", token="tok")
+    result = gitlab_request("GET", "/projects/7/issues", config=cfg, params={"state": "opened"})
+
+    assert result == [{"id": 1}]
+    assert seen["url"] == "https://gitlab.example.com/api/v4/projects/7/issues?state=opened"
+    assert seen["method"] == "GET"
+    assert seen["token"] == "tok"
+
+
+def test_gitlab_request_drops_none_and_renders_bools(monkeypatch):
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["query"] = dict(request.url.params)
+        return httpx.Response(200, json=[])
+
+    mock_request(monkeypatch, handler)
+    cfg = GitlabConfig(base_url="https://gl", token="tok")
+    gitlab_request("GET", "/x", config=cfg, params={"recursive": True, "membership": False, "ref": None})
+
+    assert seen["query"] == {"recursive": "true", "membership": "false"}
+
+
+def test_gitlab_request_raw_returns_text(monkeypatch):
+    mock_request(monkeypatch, lambda req: httpx.Response(200, text="line1\nline2\n"))
+    cfg = GitlabConfig(base_url="https://gl", token="tok")
+    assert gitlab_request("GET", "/jobs/1/trace", config=cfg, raw=True) == "line1\nline2\n"
+
+
+def test_gitlab_request_none_on_204(monkeypatch):
+    mock_request(monkeypatch, lambda req: httpx.Response(204))
+    cfg = GitlabConfig(base_url="https://gl", token="tok")
+    assert gitlab_request("GET", "/x", config=cfg) is None
+
+
+def test_gitlab_request_raises_string_message(monkeypatch):
+    mock_request(monkeypatch, lambda req: httpx.Response(404, json={"message": "404 Project Not Found"}))
+    cfg = GitlabConfig(base_url="https://gl", token="tok")
+    with pytest.raises(GitlabError, match="Project Not Found"):
+        gitlab_request("GET", "/projects/nope", config=cfg)
+
+
+def test_gitlab_request_raises_dict_message(monkeypatch):
+    mock_request(monkeypatch, lambda req: httpx.Response(400, json={"message": {"labels": ["is invalid"]}}))
+    cfg = GitlabConfig(base_url="https://gl", token="tok")
+    with pytest.raises(GitlabError, match="labels: is invalid"):
+        gitlab_request("GET", "/x", config=cfg)
+
+
+def test_gitlab_request_raises_oauth_error(monkeypatch):
+    mock_request(monkeypatch, lambda req: httpx.Response(401, json={"error": "invalid_token", "error_description": "token expired"}))
+    cfg = GitlabConfig(base_url="https://gl", token="tok")
+    with pytest.raises(GitlabError, match="token expired"):
+        gitlab_request("GET", "/user", config=cfg)