runspec-gitlab-core 0.1.0__py3-none-any.whl

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/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/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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+runspec_gitlab_core/__init__.py,sha256=mFZzpF5lu0NXMeL6dHq3TEnu9g0NKzZMCxPC3mYBv8Q,2073
+runspec_gitlab_core/client.py,sha256=7OXdxkFXwsMV2bv5_vNygS_StjjbCyDebW4ntHuMdiM,6004
+runspec_gitlab_core/issues.py,sha256=U3uEmiAV59Be4gLo47Vn_ZC7NgehKEiOMdWSNmUGsbo,1282
+runspec_gitlab_core/merge_requests.py,sha256=JdcW_yqkR5U1qoP-xNJUTN1pxE5qaDObcT4TMhuYbFU,1438
+runspec_gitlab_core/pipelines.py,sha256=fvqdv7cUKJbKNDKk8eTMB98GAPK37olFhWrLB4jk2Ts,2029
+runspec_gitlab_core/projects.py,sha256=Npx4Cv1c9dL9sNd2ugd27Xb98wv_wi4wiSnTuxTyz6w,1665
+runspec_gitlab_core/repository.py,sha256=tbo8OmryMuzGYux8fExiHUPkyQLWVNIGOavDn4E8j8Q,2064
+runspec_gitlab_core-0.1.0.dist-info/METADATA,sha256=UzoOYNvw95wm1QnDN9WHE_YCJ0I_OxZl4YMIKlrbEAE,377
+runspec_gitlab_core-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+runspec_gitlab_core-0.1.0.dist-info/RECORD,,

runspec_gitlab_core-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any