runspec-gitlab 0.1.0__py3-none-any.whl

runspec_gitlab/__init__.py

@@ -0,0 +1,54 @@
+"""runspec-gitlab — GitLab reads as a runspec runnable (the ``gitlab`` runnable).
+
+Ported from the
+`GitLab MCP server <https://docs.gitlab.com/user/model_context_protocol/mcp_server/>`_.
+The pure REST logic lives in ``runspec-gitlab-core`` (importable with **no**
+runspec dependency); this package wraps each helper as a verb of the ``gitlab``
+runnable and is what ``runspec local`` / ``runspec serve`` discover.
+
+The core helpers are re-exported here for convenience / back-compat, so a caller
+that already depends on ``runspec-gitlab`` can ``from runspec_gitlab import
+list_issues`` without also naming ``runspec-gitlab-core``.
+"""
+
+from runspec_gitlab_core import (
+    GitlabConfig,
+    GitlabError,
+    config_from_env,
+    encode_project,
+    get_file,
+    get_issue,
+    get_job_log,
+    get_merge_request,
+    get_merge_request_changes,
+    get_pipeline_jobs,
+    get_project,
+    gitlab_request,
+    list_issues,
+    list_merge_requests,
+    list_pipelines,
+    list_tree,
+    search_projects,
+    whoami,
+)
+
+__all__ = [
+    "GitlabConfig",
+    "GitlabError",
+    "config_from_env",
+    "gitlab_request",
+    "encode_project",
+    "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/cli.py

@@ -0,0 +1,132 @@
+"""cli.py — the ``gitlab`` entry point.
+
+One binary, a verb per GitLab MCP read tool. ``rs.parse("gitlab")`` resolves the
+subcommand and its args; we build a :class:`GitlabConfig` from the environment
+(scoped by the global ``--env``), unpack each ``.value`` at the boundary, and call
+the matching :mod:`runspec_gitlab_core` helper.
+
+Failures (the ``runspec_gitlab_core`` :class:`GitlabError` and arg-shape
+``ValueError``s) become a JSON ``{"error": ...}`` payload + a non-zero exit.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+import runspec as rs
+from runspec_gitlab_core import (
+    GitlabConfig,
+    GitlabError,
+    config_from_env,
+    get_file,
+    get_issue,
+    get_job_log,
+    get_merge_request,
+    get_merge_request_changes,
+    get_pipeline_jobs,
+    get_project,
+    list_issues,
+    list_merge_requests,
+    list_pipelines,
+    list_tree,
+    search_projects,
+    whoami,
+)
+
+
+def _emit(payload: Any) -> None:
+    print(json.dumps(payload, default=str))
+
+
+def _dispatch(spec: rs.RunSpec, config: GitlabConfig) -> Any:
+    """Run the active verb against ``config``, unpacking ``spec.<arg>.value`` for
+    only the args the verb declares (globals + its own)."""
+    command = spec.runspec_command
+
+    if command == "whoami":
+        return whoami(config)
+    if command == "get-project":
+        return get_project(config, project=spec.project.value)
+    if command == "search-projects":
+        return search_projects(
+            config,
+            search=spec.search.value,
+            membership=spec.membership.value,
+            per_page=spec.per_page.value,
+            page=spec.page.value,
+        )
+    if command == "list-issues":
+        return list_issues(
+            config,
+            project=spec.project.value,
+            state=spec.state.value,
+            labels=spec.labels.value,
+            search=spec.search.value,
+            per_page=spec.per_page.value,
+            page=spec.page.value,
+        )
+    if command == "get-issue":
+        return get_issue(config, issue_iid=spec.issue_iid.value, project=spec.project.value)
+    if command == "list-merge-requests":
+        return list_merge_requests(
+            config,
+            project=spec.project.value,
+            state=spec.state.value,
+            per_page=spec.per_page.value,
+            page=spec.page.value,
+        )
+    if command == "get-merge-request":
+        return get_merge_request(config, mr_iid=spec.mr_iid.value, project=spec.project.value)
+    if command == "get-merge-request-changes":
+        return get_merge_request_changes(config, mr_iid=spec.mr_iid.value, project=spec.project.value)
+    if command == "list-pipelines":
+        return list_pipelines(
+            config,
+            project=spec.project.value,
+            ref=spec.ref.value,
+            status=spec.status.value,
+            per_page=spec.per_page.value,
+            page=spec.page.value,
+        )
+    if command == "get-pipeline-jobs":
+        return get_pipeline_jobs(
+            config,
+            pipeline_id=spec.pipeline_id.value,
+            project=spec.project.value,
+            per_page=spec.per_page.value,
+            page=spec.page.value,
+        )
+    if command == "get-job-log":
+        return get_job_log(config, job_id=spec.job_id.value, project=spec.project.value, tail=spec.tail.value)
+    if command == "get-file":
+        return get_file(config, file_path=spec.file_path.value, ref=spec.ref.value, project=spec.project.value)
+    if command == "list-tree":
+        return list_tree(
+            config,
+            path=spec.path.value,
+            ref=spec.ref.value,
+            recursive=spec.recursive.value,
+            project=spec.project.value,
+            per_page=spec.per_page.value,
+            page=spec.page.value,
+        )
+
+    # require-command = true makes a bare invocation unreachable.
+    raise SystemExit("no command — see `gitlab --help`")  # pragma: no cover
+
+
+def main() -> None:
+    spec = rs.parse("gitlab")
+    try:
+        config = config_from_env(env=spec.env.value)
+        result = _dispatch(spec, config)
+    except (GitlabError, ValueError) as exc:
+        _emit({"error": str(exc), "kind": type(exc).__name__})
+        sys.exit(1)
+    _emit(result)
+
+
+if __name__ == "__main__":
+    main()

runspec_gitlab/runspec.toml

@@ -0,0 +1,156 @@
+#:schema https://runspec.app/runspec.schema.json
+
+# runspec-gitlab — GitLab reads as a runspec runnable, ported from the GitLab MCP
+# server: https://docs.gitlab.com/user/model_context_protocol/mcp_server/
+#
+# One runnable, `gitlab`, with a verb per read tool. `runspec serve` re-expands
+# each verb into its own leaf MCP tool (gitlab_get-issue, gitlab_list-pipelines,
+# …), so a runspec-console agent calls them individually — over SSH on any fleet
+# host.
+#
+# The tools are PORTED onto the GitLab REST API (v4), not proxied from GitLab's
+# hosted MCP server, so no extra process is involved. Auth is env-var driven:
+#   GITLAB_URL  (default https://gitlab.com) + GITLAB_TOKEN  (a personal access
+#   token). Per-environment overrides use a GITLAB_<ENV>_ prefix (e.g.
+#   GITLAB_UAT_TOKEN), selected with the global --env (dev/uat/prod) arg.
+#
+# `project` accepts a numeric id or a URL-path (`group/subgroup/project`); it
+# falls back to GITLAB_PROJECT when omitted.
+
+[config]
+autonomy-default = "confirm"
+
+[config.logging]
+store = "per-run"
+
+[gitlab]
+description = "Read GitLab issues, merge requests, pipelines, and repository files (over the REST API)"
+output = "json"
+require-command = true
+examples = [
+  {cmd = "gitlab whoami", description = "Verify the token and show the authenticated user"},
+  {cmd = "gitlab list-issues --project group/app --state opened", description = "List a project's open issues"},
+  {cmd = "gitlab get-merge-request-changes --project 42 --mr-iid 17", description = "Show a merge request's diffs"},
+  {cmd = "gitlab get-job-log --project group/app --job-id 9001 --tail 100", description = "Tail the last 100 lines of a CI job log"},
+  {cmd = "gitlab get-file --project group/app --file-path src/main.py --ref main", description = "Read a repository file at a ref"},
+]
+
+# ── global args (inherited by every verb) ──────────────────────────────────
+[gitlab.args]
+env = {type = "choice", options = ["dev", "uat", "prod"], short = "-e", required = false, description = "Target environment (selects GITLAB_<ENV>_* vars)"}
+
+# ── identity / projects ────────────────────────────────────────────────────
+
+[gitlab.commands.whoami]
+description = "Return the authenticated user for the configured token (a quick identity/token check)"
+autonomy = "autonomous"
+
+[gitlab.commands.get-project]
+description = "Fetch a single project's metadata by numeric id or namespace/project path"
+autonomy = "autonomous"
+[gitlab.commands.get-project.args]
+project = {type = "str", short = "-p", required = false, description = "Project id or path (falls back to GITLAB_PROJECT)"}
+
+[gitlab.commands.search-projects]
+description = "Search visible projects by name/path"
+autonomy = "autonomous"
+[gitlab.commands.search-projects.args]
+search = {type = "str", required = true, description = "Text to match against project name/path"}
+membership = {type = "flag", default = false, description = "Only projects the token's user is a member of"}
+per-page = {type = "int", default = 20, description = "Results per page (GitLab caps at 100)"}
+page = {type = "int", default = 1, description = "Page number"}
+
+# ── issues ─────────────────────────────────────────────────────────────────
+
+[gitlab.commands.list-issues]
+description = "List a project's issues, optionally filtered by state/labels/search"
+autonomy = "autonomous"
+[gitlab.commands.list-issues.args]
+project = {type = "str", short = "-p", required = false, description = "Project id or path (falls back to GITLAB_PROJECT)"}
+state = {type = "choice", options = ["opened", "closed", "all"], required = false, description = "Issue state filter"}
+labels = {type = "str", required = false, description = "Comma-separated label list to filter by"}
+search = {type = "str", required = false, description = "Match title/description text"}
+per-page = {type = "int", default = 20, description = "Results per page (GitLab caps at 100)"}
+page = {type = "int", default = 1, description = "Page number"}
+
+[gitlab.commands.get-issue]
+description = "Fetch a single issue by its project-scoped internal id (iid)"
+autonomy = "autonomous"
+[gitlab.commands.get-issue.args]
+project = {type = "str", short = "-p", required = false, description = "Project id or path (falls back to GITLAB_PROJECT)"}
+issue-iid = {type = "int", required = true, description = "Issue internal id (the #N shown in the UI)"}
+
+# ── merge requests ─────────────────────────────────────────────────────────
+
+[gitlab.commands.list-merge-requests]
+description = "List a project's merge requests, optionally filtered by state"
+autonomy = "autonomous"
+[gitlab.commands.list-merge-requests.args]
+project = {type = "str", short = "-p", required = false, description = "Project id or path (falls back to GITLAB_PROJECT)"}
+state = {type = "choice", options = ["opened", "closed", "merged", "locked", "all"], required = false, description = "Merge request state filter"}
+per-page = {type = "int", default = 20, description = "Results per page (GitLab caps at 100)"}
+page = {type = "int", default = 1, description = "Page number"}
+
+[gitlab.commands.get-merge-request]
+description = "Fetch a single merge request by its project-scoped internal id (iid)"
+autonomy = "autonomous"
+[gitlab.commands.get-merge-request.args]
+project = {type = "str", short = "-p", required = false, description = "Project id or path (falls back to GITLAB_PROJECT)"}
+mr-iid = {type = "int", required = true, description = "Merge request internal id (the !N shown in the UI)"}
+
+[gitlab.commands.get-merge-request-changes]
+description = "Fetch a merge request together with its file changes / diffs"
+autonomy = "autonomous"
+[gitlab.commands.get-merge-request-changes.args]
+project = {type = "str", short = "-p", required = false, description = "Project id or path (falls back to GITLAB_PROJECT)"}
+mr-iid = {type = "int", required = true, description = "Merge request internal id (the !N shown in the UI)"}
+
+# ── pipelines / jobs ───────────────────────────────────────────────────────
+
+[gitlab.commands.list-pipelines]
+description = "List a project's CI/CD pipelines, optionally filtered by ref/status"
+autonomy = "autonomous"
+[gitlab.commands.list-pipelines.args]
+project = {type = "str", short = "-p", required = false, description = "Project id or path (falls back to GITLAB_PROJECT)"}
+ref = {type = "str", required = false, description = "Branch or tag to filter by"}
+status = {type = "choice", options = ["created", "waiting_for_resource", "preparing", "pending", "running", "success", "failed", "canceled", "skipped", "manual", "scheduled"], required = false, description = "Pipeline status filter"}
+per-page = {type = "int", default = 20, description = "Results per page (GitLab caps at 100)"}
+page = {type = "int", default = 1, description = "Page number"}
+
+[gitlab.commands.get-pipeline-jobs]
+description = "List the jobs of a pipeline (by pipeline id)"
+autonomy = "autonomous"
+[gitlab.commands.get-pipeline-jobs.args]
+project = {type = "str", short = "-p", required = false, description = "Project id or path (falls back to GITLAB_PROJECT)"}
+pipeline-id = {type = "int", required = true, description = "Pipeline id (not the iid)"}
+per-page = {type = "int", default = 20, description = "Results per page (GitLab caps at 100)"}
+page = {type = "int", default = 1, description = "Page number"}
+
+[gitlab.commands.get-job-log]
+description = "Fetch a CI job's log (trace) as text; pass --tail to return only the last N lines"
+autonomy = "autonomous"
+[gitlab.commands.get-job-log.args]
+project = {type = "str", short = "-p", required = false, description = "Project id or path (falls back to GITLAB_PROJECT)"}
+job-id = {type = "int", required = true, description = "Job id"}
+tail = {type = "int", required = false, description = "Return only the last N lines (logs are large — usually pass this)"}
+
+# ── repository ─────────────────────────────────────────────────────────────
+
+[gitlab.commands.get-file]
+description = "Read a single repository file at a ref (base64 is decoded; non-UTF-8 files are flagged binary)"
+autonomy = "autonomous"
+[gitlab.commands.get-file.args]
+project = {type = "str", short = "-p", required = false, description = "Project id or path (falls back to GITLAB_PROJECT)"}
+file-path = {type = "str", required = true, description = "Path within the repository (e.g. src/main.py)"}
+ref = {type = "str", default = "HEAD", description = "Branch, tag, or commit (default HEAD = the default branch tip)"}
+
+[gitlab.commands.list-tree]
+description = "List a repository tree at a path/ref; --recursive walks subdirectories"
+autonomy = "autonomous"
+[gitlab.commands.list-tree.args]
+project = {type = "str", short = "-p", required = false, description = "Project id or path (falls back to GITLAB_PROJECT)"}
+path = {type = "str", required = false, description = "Subdirectory to list (default: repository root)"}
+ref = {type = "str", required = false, description = "Branch, tag, or commit (default: the default branch)"}
+recursive = {type = "flag", default = false, description = "Walk subdirectories recursively"}
+per-page = {type = "int", default = 20, description = "Results per page (GitLab caps at 100)"}
+page = {type = "int", default = 1, description = "Page number"}

runspec_gitlab-0.1.0.dist-info/METADATA

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: runspec-gitlab
+Version: 0.1.0
+Summary: GitLab read runnable for runspec — issues, merge requests, pipelines, and repository reads, ported from the GitLab MCP server
+Requires-Python: >=3.10
+Requires-Dist: runspec-gitlab-core>=0.1.0
+Requires-Dist: runspec>=0.44.0
+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-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+runspec_gitlab/__init__.py,sha256=-92O9N4RKyJ-dbbhc0cnGMbwonhqjOPdxj5c4I9S5DE,1416
+runspec_gitlab/cli.py,sha256=tcZSoz_WZ-4hfKq6sVdaQwAFOlrvjK7Qnm1-Xb9M3DE,4292
+runspec_gitlab/runspec.toml,sha256=Lq4akFegqi6rARlQZ3Rb2OwWOPGUqiQd-PJzgJV7laA,9838
+runspec_gitlab-0.1.0.dist-info/METADATA,sha256=5nU5HQUTJ-_mia33XR46MXqReL6SYIR6ylZ5oZX5-Bs,436
+runspec_gitlab-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+runspec_gitlab-0.1.0.dist-info/entry_points.txt,sha256=hiQySJfu_gM3uoJYUqRGyQ948-SpFPkHT8B5mLrF-nw,51
+runspec_gitlab-0.1.0.dist-info/RECORD,,

runspec_gitlab-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

runspec_gitlab-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gitlab = runspec_gitlab.cli:main