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

{runspec_gitlab_core-0.2.0 → runspec_gitlab_core-0.3.0}/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 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.

{runspec_gitlab_core-0.2.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.2.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.2.0 → runspec_gitlab_core-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runspec-gitlab-core"
-version = "0.2.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.2.0 → runspec_gitlab_core-0.3.0}/runspec_gitlab_core/__init__.py

@@ -1,4 +1,4 @@
-"""runspec-gitlab-core — pure-Python GitLab REST (v4) read helpers.
+"""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
@@ -6,8 +6,8 @@ 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
+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
@@ -23,8 +23,17 @@ from runspec_gitlab_core.client import (
     encode_project,
     gitlab_request,
 )
-from runspec_gitlab_core.issues import get_issue, list_issues
+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,
@@ -32,10 +41,30 @@ from runspec_gitlab_core.merge_requests import (
     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,
 )
-from runspec_gitlab_core.pipelines import get_job_log, get_pipeline_jobs, list_pipelines
-from runspec_gitlab_core.projects import get_project, resolve_project_path, search_projects, whoami
-from runspec_gitlab_core.repository import get_file, list_tree
 
 __all__ = [
     # client / config
@@ -45,6 +74,7 @@ __all__ = [
     "gitlab_request",
     "encode_project",
     "resolve_project_path",
+    "resolve_user_ids",
     "VALID_ENVS",
     "DEFAULT_URL",
     # identity / projects
@@ -54,6 +84,10 @@ __all__ = [
     # issues
     "list_issues",
     "get_issue",
+    "create_issue",
+    "update_issue",
+    "add_issue_note",
+    "delete_issue",
     # merge requests
     "list_merge_requests",
     "get_merge_request",
@@ -62,11 +96,26 @@ __all__ = [
     "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.2.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,6 +118,7 @@ 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,
@@ -124,6 +133,8 @@ def gitlab_request(
 
     ``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.
     """
@@ -145,10 +156,11 @@ def gitlab_request(
         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,
+        },
+    )