runspec-gitlab-core 0.1.0__tar.gz → 0.3.0__tar.gz

runspec_gitlab_core-0.3.0/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to `runspec-gitlab-core` are documented here.
+
+## [0.3.0]
+
+Write helpers, each taking a `GitlabConfig` first like the reads.
+
+- **Issues:** `create_issue`, `update_issue`, `add_issue_note`.
+- **Merge requests:** `create_merge_request`, `update_merge_request`,
+  `add_merge_request_note`, `merge_merge_request`.
+- **Repository:** `create_branch`, `write_file` (checks whether the file exists
+  on the starting branch, then creates or updates it; returns `action`
+  `created`/`updated`).
+- **Pipelines/jobs:** `create_pipeline`, `retry_pipeline`, `cancel_pipeline`,
+  `retry_job`, `cancel_job`, `play_job` (variables as `KEY=VALUE` strings).
+- **Deletes:** `delete_issue`, `delete_branch`, `delete_file`,
+  `delete_pipeline` (each returns a small `{"deleted": ...}` summary).
+- `resolve_user_ids` maps usernames to the numeric ids the write APIs take.
+- `gitlab_request` gains a `body=` JSON request body (its `None` values are
+  dropped), and `GitlabError` now carries the HTTP `status_code` of an API
+  error (`None` for a configuration error).
+- `update_issue`/`update_merge_request` raise `ValueError` when no field is
+  given, rather than sending an empty edit.
+
+## [0.2.0]
+
+Reconciled against GitLab's canonical MCP tool set.
+
+- **Renamed** `get_merge_request_changes` → `get_merge_request_diffs` — the
+  canonical name; targets the paginated `/diffs` endpoint instead of the
+  deprecated `/changes`. **Breaking** API change vs 0.1.0.
+- **Added** read helpers: `get_merge_request_commits`, `get_merge_request_notes`,
+  `get_merge_request_pipelines`, `get_merge_request_conflicts`, and
+  `resolve_project_path`.
+- `gitlab_request` gains an `api=False` mode to target `{base_url}{path}` (no
+  `/api/v4` prefix) — used only for the non-public MR conflicts web endpoint.
+- `get_merge_request_conflicts` is **best-effort**: it relays GitLab's
+  non-public web-UI conflicts endpoint (there is no public `/api/v4` one) and
+  returns its JSON verbatim, resolving a numeric project id to its
+  `namespace/path` via `resolve_project_path`.
+
+## [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 → runspec_gitlab_core-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: runspec-gitlab-core
-Version: 0.1.0
+Version: 0.3.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

{runspec_gitlab_core-0.1.0 → runspec_gitlab_core-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runspec-gitlab-core"
-version = "0.1.0"
+version = "0.3.0"
 requires-python = ">=3.10"
 description = "Pure-Python GitLab REST helpers — the importable core behind runspec-gitlab (no runspec dependency, no runnables)"
 dependencies = [

runspec_gitlab_core-0.3.0/runspec_gitlab_core/__init__.py

@@ -0,0 +1,121 @@
+"""runspec-gitlab-core — pure-Python GitLab REST (v4) read + write 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 tools of GitLab's own (hosted) MCP server onto the public
+REST API, plus REST reads and writes it has no tool for. 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 (
+    add_issue_note,
+    create_issue,
+    delete_issue,
+    get_issue,
+    list_issues,
+    update_issue,
+)
+from runspec_gitlab_core.merge_requests import (
+    add_merge_request_note,
+    create_merge_request,
+    get_merge_request,
+    get_merge_request_commits,
+    get_merge_request_conflicts,
+    get_merge_request_diffs,
+    get_merge_request_notes,
+    get_merge_request_pipelines,
+    list_merge_requests,
+    merge_merge_request,
+    update_merge_request,
+)
+from runspec_gitlab_core.pipelines import (
+    cancel_job,
+    cancel_pipeline,
+    create_pipeline,
+    delete_pipeline,
+    get_job_log,
+    get_pipeline_jobs,
+    list_pipelines,
+    play_job,
+    retry_job,
+    retry_pipeline,
+)
+from runspec_gitlab_core.projects import get_project, resolve_project_path, resolve_user_ids, search_projects, whoami
+from runspec_gitlab_core.repository import (
+    create_branch,
+    delete_branch,
+    delete_file,
+    get_file,
+    list_tree,
+    write_file,
+)
+
+__all__ = [
+    # client / config
+    "GitlabConfig",
+    "GitlabError",
+    "config_from_env",
+    "gitlab_request",
+    "encode_project",
+    "resolve_project_path",
+    "resolve_user_ids",
+    "VALID_ENVS",
+    "DEFAULT_URL",
+    # identity / projects
+    "whoami",
+    "get_project",
+    "search_projects",
+    # issues
+    "list_issues",
+    "get_issue",
+    "create_issue",
+    "update_issue",
+    "add_issue_note",
+    "delete_issue",
+    # merge requests
+    "list_merge_requests",
+    "get_merge_request",
+    "get_merge_request_diffs",
+    "get_merge_request_commits",
+    "get_merge_request_notes",
+    "get_merge_request_pipelines",
+    "get_merge_request_conflicts",
+    "create_merge_request",
+    "update_merge_request",
+    "add_merge_request_note",
+    "merge_merge_request",
+    # pipelines / jobs
+    "list_pipelines",
+    "get_pipeline_jobs",
+    "get_job_log",
+    "create_pipeline",
+    "retry_pipeline",
+    "cancel_pipeline",
+    "retry_job",
+    "cancel_job",
+    "play_job",
+    "delete_pipeline",
+    # repository
+    "get_file",
+    "list_tree",
+    "create_branch",
+    "write_file",
+    "delete_branch",
+    "delete_file",
+]

{runspec_gitlab_core-0.1.0 → runspec_gitlab_core-0.3.0}/runspec_gitlab_core/client.py

@@ -29,7 +29,15 @@ DEFAULT_URL = "https://gitlab.com"
 
 
 class GitlabError(Exception):
-    """Raised on configuration problems and non-2xx API responses."""
+    """Raised on configuration problems and non-2xx API responses.
+
+    ``status_code`` carries the HTTP status for an API error (``None`` for a
+    configuration problem), so a caller can tell e.g. a 404 from a 403.
+    """
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
 
 
 @dataclass
@@ -110,14 +118,23 @@ def gitlab_request(
     *,
     config: GitlabConfig,
     params: dict[str, Any] | None = None,
+    body: dict[str, Any] | None = None,
     raw: bool = False,
+    api: bool = True,
     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).
+    """Make an authenticated request and return the parsed JSON body (or the raw
+    text when ``raw=True`` — used for job traces).
+
+    By default the request targets the public REST API at ``{base_url}/api/v4``.
+    Pass ``api=False`` to hit ``{base_url}{path}`` directly — used only for the
+    non-public web endpoints GitLab does not expose under ``/api/v4`` (e.g. the
+    merge-request conflicts endpoint).
 
     ``path`` should start with ``/`` (e.g. ``/projects/1/issues``). ``None`` values
     in ``params`` are dropped and booleans are rendered as ``"true"``/``"false"``.
+    ``body`` is sent as a JSON request body (write operations); its ``None``
+    values are dropped too, so callers can pass every optional field.
     Raises :class:`GitlabError` on any non-2xx response, surfacing the server's
     error message.
     """
@@ -133,15 +150,17 @@ def gitlab_request(
                 continue
             clean[key] = "true" if value is True else "false" if value is False else value
 
+    prefix = "/api/v4" if api else ""
     resp = httpx.request(
         method,
-        f"{config.base_url}/api/v4{path}",
+        f"{config.base_url}{prefix}{path}",
         headers=headers,
         params=clean,
+        json={k: v for k, v in body.items() if v is not None} if body is not None else None,
         timeout=timeout,
     )
     if resp.status_code >= 400:
-        raise GitlabError(_error_message(resp))
+        raise GitlabError(_error_message(resp), status_code=resp.status_code)
     if resp.status_code == 204 or not resp.content:
         return "" if raw else None
     if raw:

runspec_gitlab_core-0.3.0/runspec_gitlab_core/issues.py

@@ -0,0 +1,143 @@
+"""issues.py — project issue operations (GitLab REST v4): reads + writes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runspec_gitlab_core.client import GitlabConfig, gitlab_request
+from runspec_gitlab_core.projects import _project, resolve_user_ids
+
+
+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,
+    )
+
+
+def _labels(labels: list[str] | None) -> str | None:
+    """Render a label list as GitLab's comma-separated form (``None`` = unset)."""
+    if labels is None:
+        return None
+    return ",".join(label.strip() for label in labels if label.strip())
+
+
+def create_issue(
+    config: GitlabConfig,
+    title: str,
+    description: str | None = None,
+    labels: list[str] | None = None,
+    assignees: list[str] | None = None,
+    milestone_id: int | None = None,
+    due_date: str | None = None,
+    confidential: bool = False,
+    project: str | None = None,
+) -> dict[str, Any]:
+    """Create an issue (the canonical ``create_issue`` tool).
+
+    ``assignees`` are usernames (or numeric ids); ``due_date`` is ``YYYY-MM-DD``.
+    Returns the created issue.
+    """
+    return gitlab_request(
+        "POST",
+        f"/projects/{_project(config, project)}/issues",
+        config=config,
+        body={
+            "title": title,
+            "description": description,
+            "labels": _labels(labels),
+            "assignee_ids": resolve_user_ids(config, assignees),
+            "milestone_id": milestone_id,
+            "due_date": due_date,
+            "confidential": confidential or None,
+        },
+    )
+
+
+def update_issue(
+    config: GitlabConfig,
+    issue_iid: int,
+    title: str | None = None,
+    description: str | None = None,
+    add_labels: list[str] | None = None,
+    remove_labels: list[str] | None = None,
+    assignees: list[str] | None = None,
+    milestone_id: int | None = None,
+    due_date: str | None = None,
+    state_event: str | None = None,
+    project: str | None = None,
+) -> dict[str, Any]:
+    """Edit an issue. Only the fields passed change; ``state_event`` is
+    ``close``/``reopen``. Raises :class:`ValueError` when nothing would change."""
+    body = {
+        "title": title,
+        "description": description,
+        "add_labels": _labels(add_labels),
+        "remove_labels": _labels(remove_labels),
+        "assignee_ids": resolve_user_ids(config, assignees),
+        "milestone_id": milestone_id,
+        "due_date": due_date,
+        "state_event": state_event,
+    }
+    if all(value is None for value in body.values()):
+        raise ValueError("Nothing to update — pass at least one field to change")
+    return gitlab_request(
+        "PUT",
+        f"/projects/{_project(config, project)}/issues/{issue_iid}",
+        config=config,
+        body=body,
+    )
+
+
+def add_issue_note(
+    config: GitlabConfig,
+    issue_iid: int,
+    body: str,
+    internal: bool = False,
+    project: str | None = None,
+) -> dict[str, Any]:
+    """Comment on an issue. ``internal`` makes it an internal note (visible to
+    project members with at least Reporter access only)."""
+    return gitlab_request(
+        "POST",
+        f"/projects/{_project(config, project)}/issues/{issue_iid}/notes",
+        config=config,
+        body={"body": body, "internal": internal or None},
+    )
+
+
+def delete_issue(config: GitlabConfig, issue_iid: int, project: str | None = None) -> dict[str, Any]:
+    """Delete an issue permanently. GitLab only allows this for project owners
+    and administrators."""
+    gitlab_request("DELETE", f"/projects/{_project(config, project)}/issues/{issue_iid}", config=config)
+    return {"deleted": "issue", "issue_iid": issue_iid}

runspec_gitlab_core-0.3.0/runspec_gitlab_core/merge_requests.py

@@ -0,0 +1,251 @@
+"""merge_requests.py — merge-request operations (GitLab REST v4): reads + writes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runspec_gitlab_core.client import GitlabConfig, gitlab_request
+from runspec_gitlab_core.issues import _labels
+from runspec_gitlab_core.projects import _project, resolve_project_path, resolve_user_ids
+
+
+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_diffs(
+    config: GitlabConfig,
+    mr_iid: int,
+    project: str | None = None,
+    per_page: int = 20,
+    page: int = 1,
+) -> list[dict[str, Any]]:
+    """List a merge request's file diffs.
+
+    Mirrors the canonical ``get_merge_request_diffs`` MCP tool — the paginated
+    ``/merge_requests/:iid/diffs`` endpoint, not the deprecated ``/changes``.
+    """
+    return gitlab_request(
+        "GET",
+        f"/projects/{_project(config, project)}/merge_requests/{mr_iid}/diffs",
+        config=config,
+        params={"per_page": per_page, "page": page},
+    )
+
+
+def get_merge_request_commits(
+    config: GitlabConfig,
+    mr_iid: int,
+    project: str | None = None,
+    per_page: int = 20,
+    page: int = 1,
+) -> list[dict[str, Any]]:
+    """List the commits on a merge request (canonical ``get_merge_request_commits``)."""
+    return gitlab_request(
+        "GET",
+        f"/projects/{_project(config, project)}/merge_requests/{mr_iid}/commits",
+        config=config,
+        params={"per_page": per_page, "page": page},
+    )
+
+
+def get_merge_request_notes(
+    config: GitlabConfig,
+    mr_iid: int,
+    project: str | None = None,
+    sort: str | None = None,
+    per_page: int = 20,
+    page: int = 1,
+) -> list[dict[str, Any]]:
+    """List a merge request's notes (comments) — the REST equivalent of the
+    canonical ``get_merge_request_notes`` tool. ``sort`` is ``asc``/``desc``."""
+    return gitlab_request(
+        "GET",
+        f"/projects/{_project(config, project)}/merge_requests/{mr_iid}/notes",
+        config=config,
+        params={"sort": sort, "per_page": per_page, "page": page},
+    )
+
+
+def get_merge_request_pipelines(
+    config: GitlabConfig,
+    mr_iid: int,
+    project: str | None = None,
+    per_page: int = 20,
+    page: int = 1,
+) -> list[dict[str, Any]]:
+    """List the pipelines run for a merge request (canonical ``get_merge_request_pipelines``)."""
+    return gitlab_request(
+        "GET",
+        f"/projects/{_project(config, project)}/merge_requests/{mr_iid}/pipelines",
+        config=config,
+        params={"per_page": per_page, "page": page},
+    )
+
+
+def get_merge_request_conflicts(config: GitlabConfig, mr_iid: int, project: str | None = None) -> Any:
+    """Fetch a merge request's conflict files (the canonical ``get_merge_request_conflicts``).
+
+    **Best-effort — not a public REST API.** GitLab exposes MR conflict *contents*
+    only through its web-UI endpoint (``{base}/{namespace}/{project}/-/merge_requests/
+    :iid/conflicts``), not under ``/api/v4``; the MCP server's own tool calls an
+    internal service in-process. This relays that endpoint's JSON verbatim (files
+    with conflict markers/sections), so its shape is GitLab's, not ours, and may
+    change between versions. Requires a token with read access to the MR (and,
+    per GitLab, push access to the source branch). A non-conflicting or
+    unmergeable MR typically yields a non-2xx surfaced as :class:`GitlabError`.
+    """
+    path = resolve_project_path(config, project)
+    return gitlab_request(
+        "GET",
+        f"/{path}/-/merge_requests/{mr_iid}/conflicts",
+        config=config,
+        api=False,
+    )
+
+
+DRAFT_PREFIX = "Draft: "
+
+
+def create_merge_request(
+    config: GitlabConfig,
+    source_branch: str,
+    target_branch: str,
+    title: str,
+    description: str | None = None,
+    draft: bool = False,
+    labels: list[str] | None = None,
+    assignees: list[str] | None = None,
+    reviewers: list[str] | None = None,
+    remove_source_branch: bool = False,
+    squash: bool = False,
+    project: str | None = None,
+) -> dict[str, Any]:
+    """Open a merge request (the canonical ``create_merge_request`` tool).
+
+    ``draft`` prefixes the title with ``Draft: `` (GitLab's draft marker);
+    ``assignees``/``reviewers`` are usernames (or numeric ids).
+    """
+    if draft and not title.lower().startswith(("draft:", "[draft]", "(draft)")):
+        title = DRAFT_PREFIX + title
+    return gitlab_request(
+        "POST",
+        f"/projects/{_project(config, project)}/merge_requests",
+        config=config,
+        body={
+            "source_branch": source_branch,
+            "target_branch": target_branch,
+            "title": title,
+            "description": description,
+            "labels": _labels(labels),
+            "assignee_ids": resolve_user_ids(config, assignees),
+            "reviewer_ids": resolve_user_ids(config, reviewers),
+            "remove_source_branch": remove_source_branch or None,
+            "squash": squash or None,
+        },
+    )
+
+
+def update_merge_request(
+    config: GitlabConfig,
+    mr_iid: int,
+    title: str | None = None,
+    description: str | None = None,
+    target_branch: str | None = None,
+    add_labels: list[str] | None = None,
+    remove_labels: list[str] | None = None,
+    assignees: list[str] | None = None,
+    reviewers: list[str] | None = None,
+    state_event: str | None = None,
+    project: str | None = None,
+) -> dict[str, Any]:
+    """Edit a merge request. Only the fields passed change; ``state_event`` is
+    ``close``/``reopen``. Raises :class:`ValueError` when nothing would change."""
+    body = {
+        "title": title,
+        "description": description,
+        "target_branch": target_branch,
+        "add_labels": _labels(add_labels),
+        "remove_labels": _labels(remove_labels),
+        "assignee_ids": resolve_user_ids(config, assignees),
+        "reviewer_ids": resolve_user_ids(config, reviewers),
+        "state_event": state_event,
+    }
+    if all(value is None for value in body.values()):
+        raise ValueError("Nothing to update — pass at least one field to change")
+    return gitlab_request(
+        "PUT",
+        f"/projects/{_project(config, project)}/merge_requests/{mr_iid}",
+        config=config,
+        body=body,
+    )
+
+
+def add_merge_request_note(
+    config: GitlabConfig,
+    mr_iid: int,
+    body: str,
+    internal: bool = False,
+    project: str | None = None,
+) -> dict[str, Any]:
+    """Comment on a merge request (a general, non-diff note)."""
+    return gitlab_request(
+        "POST",
+        f"/projects/{_project(config, project)}/merge_requests/{mr_iid}/notes",
+        config=config,
+        body={"body": body, "internal": internal or None},
+    )
+
+
+def merge_merge_request(
+    config: GitlabConfig,
+    mr_iid: int,
+    sha: str | None = None,
+    squash: bool | None = None,
+    remove_source_branch: bool | None = None,
+    when_pipeline_succeeds: bool = False,
+    merge_commit_message: str | None = None,
+    project: str | None = None,
+) -> dict[str, Any]:
+    """Merge a merge request (or set it to merge when its pipeline succeeds).
+
+    ``sha`` guards the merge: GitLab refuses if the source branch head moved
+    since you reviewed it. ``squash``/``remove_source_branch`` left as ``None``
+    keep the MR's own settings.
+    """
+    return gitlab_request(
+        "PUT",
+        f"/projects/{_project(config, project)}/merge_requests/{mr_iid}/merge",
+        config=config,
+        body={
+            "sha": sha,
+            "squash": squash,
+            "should_remove_source_branch": remove_source_branch,
+            "merge_when_pipeline_succeeds": when_pipeline_succeeds or None,
+            "merge_commit_message": merge_commit_message,
+        },
+    )