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

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

@@ -2,6 +2,39 @@
 
 All notable changes to `runspec-gitlab` are documented here.
 
+## [0.3.0] — 2026-10-10
+
+### Added
+
+- **15 write verbs**, all `autonomy = "confirm"` (the 17 read verbs stay
+  `autonomous`):
+  - issues: `create-issue`, `update-issue` (title/description, add/remove
+    labels, assignees, milestone, due date, close/reopen), `add-issue-note`;
+  - merge requests: `create-merge-request` (`--draft`, reviewers, squash,
+    remove source branch), `update-merge-request`, `add-merge-request-note`,
+    `merge-merge-request` (`--sha` guard, `--when-pipeline-succeeds`);
+  - repository: `create-branch`, `write-file` (creates or replaces a text file
+    in one commit, from `--content` or `--content-file`, optionally on a new
+    branch via `--start-branch`);
+  - pipelines/jobs: `create-pipeline` (`--variable KEY=VALUE`),
+    `retry-pipeline`, `cancel-pipeline`, `retry-job`, `cancel-job`, `play-job`.
+- **4 delete verbs**, all `autonomy = "manual"` so an agent can never run
+  them (a person can, from the CLI or the console's Forms tab):
+  `delete-issue`, `delete-branch`, `delete-file`, `delete-pipeline`.
+- Assignees and reviewers are taken as usernames. Writes and deletes need a
+  token with the `api` scope.
+- Requires `runspec-gitlab-core >= 0.3.0`.
+
+## [0.2.1] — 2026-09-20
+
+### Changed
+
+- **Packaging metadata for the runspec-console Marketplace.** Add a README
+  (rendered in the Marketplace card's Details view) and publish `keywords`
+  and Documentation / Source / Changelog / Issues project URLs, so the
+  package's Marketplace card shows a description, tags and links. No
+  runnable, argument, or behaviour changes.
+
 ## [0.2.0]
 
 Reconciled the verb set against GitLab's canonical MCP tool registry

runspec_gitlab-0.3.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.5
+Name: runspec-gitlab
+Version: 0.3.0
+Summary: GitLab runnable for runspec — read and update issues, merge requests, pipelines, and repository files, ported from the GitLab MCP server
+Project-URL: Documentation, https://runspec.app/
+Project-URL: Source, https://github.com/jasonfinestone/runspec/tree/main/packages/python/runspec-gitlab
+Project-URL: Changelog, https://github.com/jasonfinestone/runspec/blob/main/packages/python/runspec-gitlab/CHANGELOG.md
+Project-URL: Issues, https://github.com/jasonfinestone/runspec/issues
+Keywords: gitlab,mcp,runnable,runspec
+Requires-Python: >=3.10
+Requires-Dist: runspec-gitlab-core>=0.3.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'
+Description-Content-Type: text/markdown
+
+# runspec-gitlab
+
+A GitLab runnable for [runspec](https://pypi.org/project/runspec/), ported onto
+the GitLab REST API (v4) — **not** proxying GitLab's hosted MCP server. One
+runnable — **`gitlab`** — with 17 read verbs (`autonomy = "autonomous"`), 15
+write verbs (`autonomy = "confirm"`, so an agent asks before each one) and 4
+delete verbs (`autonomy = "manual"`, so only a person can run them). `pip install` it into a venv and it's discoverable by `runspec
+local`, `runspec serve` (MCP), and runspec-console.
+
+`runspec serve` flattens each verb into a leaf MCP tool (`gitlab_get-issue`, …).
+Verb names are reconciled against GitLab's canonical MCP tool registry; the
+extras (`whoami`, `get-project`, `search-projects`, `list-issues`, `get-file`,
+`list-tree`) are useful REST reads GitLab has no MCP tool for.
+
+## Install
+
+```
+pip install runspec-gitlab
+```
+
+## Verbs
+
+| Area | Verbs |
+|---|---|
+| Account / project | `whoami`, `get-project`, `search-projects`, `get-file`, `list-tree` |
+| Issues | `list-issues`, `get-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` |
+| Pipelines | `list-pipelines`, `get-pipeline-jobs`, `get-job-log` |
+
+Writes (all `confirm`):
+
+| Area | Verbs |
+|---|---|
+| Issues | `create-issue`, `update-issue` (edit, labels, assignees, close/reopen), `add-issue-note` |
+| Merge requests | `create-merge-request`, `update-merge-request` (edit, labels, assignees, reviewers, close/reopen), `add-merge-request-note`, `merge-merge-request` |
+| Repository | `create-branch`, `write-file` (create or replace a text file in one commit) |
+| Pipelines / jobs | `create-pipeline`, `retry-pipeline`, `cancel-pipeline`, `retry-job`, `cancel-job`, `play-job` |
+
+Assignees and reviewers are given as usernames. Labels, assignees, reviewers and
+pipeline variables (`KEY=VALUE`) are repeatable args. Writes need a token with
+the `api` scope; reads work with `read_api`.
+
+Deletes (all `manual` — refused to an agent, run from the command line or the
+console's Forms tab): `delete-issue`, `delete-branch`, `delete-file`,
+`delete-pipeline`. GitLab itself limits issue and pipeline deletes to project
+owners/admins and refuses protected or default branches.
+
+`get-merge-request-conflicts` is best-effort — GitLab has no public `/api/v4`
+conflicts endpoint, so it relays the web-UI endpoint and returns its JSON
+verbatim.
+
+## Auth — env vars only
+
+```
+export GITLAB_URL=https://gitlab.example.com        # default https://gitlab.com
+export GITLAB_TOKEN=<personal-or-project-access-token>
+export GITLAB_PROJECT=group/subgroup/project        # optional default
+```
+
+Every verb takes `--env`, selecting `GITLAB_<ENV>_*` prefixed vars. `--project`
+accepts a numeric id or a `group/project` path and falls back to
+`GITLAB_PROJECT`.
+
+```
+gitlab whoami
+gitlab list-merge-requests --project group/app --state opened
+gitlab get-job-log --project group/app --job-id 998877
+gitlab create-issue --project group/app --title "Login fails" --label bug --assignee alice
+gitlab write-file --project group/app --branch fix --start-branch main \
+  --file-path docs/notes.md --content-file notes.md --commit-message "Add notes"
+```
+
+## Public Python API
+
+The pure logic is in **[`runspec-gitlab-core`](../runspec-gitlab-core)** —
+`httpx`-only, no `runspec` dependency, no entry points. Every op takes a
+`GitlabConfig` first arg and raises `GitlabError`, so a private wrapper can
+inject credentials and bake in a default `project` / `env`:
+
+```python
+from runspec_gitlab_core import config_from_env, get_issue, list_merge_requests
+
+cfg = config_from_env(env="prod")
+mrs = list_merge_requests(cfg, state="opened")
+```
+
+## Development
+
+```
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+ruff check . && ruff format --check .
+pytest
+```

runspec_gitlab-0.3.0/README.md

@@ -0,0 +1,94 @@
+# runspec-gitlab
+
+A GitLab runnable for [runspec](https://pypi.org/project/runspec/), ported onto
+the GitLab REST API (v4) — **not** proxying GitLab's hosted MCP server. One
+runnable — **`gitlab`** — with 17 read verbs (`autonomy = "autonomous"`), 15
+write verbs (`autonomy = "confirm"`, so an agent asks before each one) and 4
+delete verbs (`autonomy = "manual"`, so only a person can run them). `pip install` it into a venv and it's discoverable by `runspec
+local`, `runspec serve` (MCP), and runspec-console.
+
+`runspec serve` flattens each verb into a leaf MCP tool (`gitlab_get-issue`, …).
+Verb names are reconciled against GitLab's canonical MCP tool registry; the
+extras (`whoami`, `get-project`, `search-projects`, `list-issues`, `get-file`,
+`list-tree`) are useful REST reads GitLab has no MCP tool for.
+
+## Install
+
+```
+pip install runspec-gitlab
+```
+
+## Verbs
+
+| Area | Verbs |
+|---|---|
+| Account / project | `whoami`, `get-project`, `search-projects`, `get-file`, `list-tree` |
+| Issues | `list-issues`, `get-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` |
+| Pipelines | `list-pipelines`, `get-pipeline-jobs`, `get-job-log` |
+
+Writes (all `confirm`):
+
+| Area | Verbs |
+|---|---|
+| Issues | `create-issue`, `update-issue` (edit, labels, assignees, close/reopen), `add-issue-note` |
+| Merge requests | `create-merge-request`, `update-merge-request` (edit, labels, assignees, reviewers, close/reopen), `add-merge-request-note`, `merge-merge-request` |
+| Repository | `create-branch`, `write-file` (create or replace a text file in one commit) |
+| Pipelines / jobs | `create-pipeline`, `retry-pipeline`, `cancel-pipeline`, `retry-job`, `cancel-job`, `play-job` |
+
+Assignees and reviewers are given as usernames. Labels, assignees, reviewers and
+pipeline variables (`KEY=VALUE`) are repeatable args. Writes need a token with
+the `api` scope; reads work with `read_api`.
+
+Deletes (all `manual` — refused to an agent, run from the command line or the
+console's Forms tab): `delete-issue`, `delete-branch`, `delete-file`,
+`delete-pipeline`. GitLab itself limits issue and pipeline deletes to project
+owners/admins and refuses protected or default branches.
+
+`get-merge-request-conflicts` is best-effort — GitLab has no public `/api/v4`
+conflicts endpoint, so it relays the web-UI endpoint and returns its JSON
+verbatim.
+
+## Auth — env vars only
+
+```
+export GITLAB_URL=https://gitlab.example.com        # default https://gitlab.com
+export GITLAB_TOKEN=<personal-or-project-access-token>
+export GITLAB_PROJECT=group/subgroup/project        # optional default
+```
+
+Every verb takes `--env`, selecting `GITLAB_<ENV>_*` prefixed vars. `--project`
+accepts a numeric id or a `group/project` path and falls back to
+`GITLAB_PROJECT`.
+
+```
+gitlab whoami
+gitlab list-merge-requests --project group/app --state opened
+gitlab get-job-log --project group/app --job-id 998877
+gitlab create-issue --project group/app --title "Login fails" --label bug --assignee alice
+gitlab write-file --project group/app --branch fix --start-branch main \
+  --file-path docs/notes.md --content-file notes.md --commit-message "Add notes"
+```
+
+## Public Python API
+
+The pure logic is in **[`runspec-gitlab-core`](../runspec-gitlab-core)** —
+`httpx`-only, no `runspec` dependency, no entry points. Every op takes a
+`GitlabConfig` first arg and raises `GitlabError`, so a private wrapper can
+inject credentials and bake in a default `project` / `env`:
+
+```python
+from runspec_gitlab_core import config_from_env, get_issue, list_merge_requests
+
+cfg = config_from_env(env="prod")
+mrs = list_merge_requests(cfg, state="opened")
+```
+
+## Development
+
+```
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+ruff check . && ruff format --check .
+pytest
+```

{runspec_gitlab-0.2.0 → runspec_gitlab-0.3.0}/pyproject.toml

@@ -4,16 +4,24 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runspec-gitlab"
-version = "0.2.0"
+version = "0.3.0"
 requires-python = ">=3.10"
-description = "GitLab read runnable for runspec — issues, merge requests, pipelines, and repository reads, ported from the GitLab MCP server"
+description = "GitLab runnable for runspec — read and update issues, merge requests, pipelines, and repository files, ported from the GitLab MCP server"
+readme = "README.md"
+keywords = ["runspec", "runnable", "gitlab", "mcp"]
 dependencies = [
     # 0.44.0 surfaces inherited args (the global --env) on each leaf subcommand's
     # MCP tool via `runspec serve`.
     "runspec>=0.44.0",
-    "runspec-gitlab-core>=0.2.0",
+    "runspec-gitlab-core>=0.3.0",
 ]
 
+[project.urls]
+Documentation = "https://runspec.app/"
+Source        = "https://github.com/jasonfinestone/runspec/tree/main/packages/python/runspec-gitlab"
+Changelog     = "https://github.com/jasonfinestone/runspec/blob/main/packages/python/runspec-gitlab/CHANGELOG.md"
+Issues        = "https://github.com/jasonfinestone/runspec/issues"
+
 [project.scripts]
 # Entry point name MUST match the runnable name in runspec.toml (`gitlab`).
 gitlab = "runspec_gitlab.cli:main"

runspec_gitlab-0.3.0/runspec_gitlab/cli.py

@@ -0,0 +1,330 @@
+"""cli.py — the ``gitlab`` entry point.
+
+One binary, a verb per GitLab tool (reads + writes). ``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 pathlib import Path
+from typing import Any
+
+import runspec as rs
+from runspec_gitlab_core import (
+    GitlabConfig,
+    GitlabError,
+    add_issue_note,
+    add_merge_request_note,
+    cancel_job,
+    cancel_pipeline,
+    config_from_env,
+    create_branch,
+    create_issue,
+    create_merge_request,
+    create_pipeline,
+    delete_branch,
+    delete_file,
+    delete_issue,
+    delete_pipeline,
+    get_file,
+    get_issue,
+    get_job_log,
+    get_merge_request,
+    get_merge_request_commits,
+    get_merge_request_conflicts,
+    get_merge_request_diffs,
+    get_merge_request_notes,
+    get_merge_request_pipelines,
+    get_pipeline_jobs,
+    get_project,
+    list_issues,
+    list_merge_requests,
+    list_pipelines,
+    list_tree,
+    merge_merge_request,
+    play_job,
+    retry_job,
+    retry_pipeline,
+    search_projects,
+    update_issue,
+    update_merge_request,
+    whoami,
+    write_file,
+)
+
+
+def _emit(payload: Any) -> None:
+    print(json.dumps(payload, default=str))
+
+
+def _list(arg: rs.Arg) -> list[str] | None:
+    """A repeatable arg's values, or ``None`` when it wasn't given (so the core
+    leaves that field unchanged rather than clearing it)."""
+    return list(arg.value) if arg.value else None
+
+
+def _content(spec: rs.RunSpec) -> str:
+    """``write-file`` content: ``--content`` verbatim, or the text of
+    ``--content-file`` (the group guarantees exactly one is set)."""
+    if spec.content_file.value is not None:
+        return Path(spec.content_file.value).read_text(encoding="utf-8")
+    return spec.content.value
+
+
+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-diffs":
+        return get_merge_request_diffs(
+            config,
+            mr_iid=spec.mr_iid.value,
+            project=spec.project.value,
+            per_page=spec.per_page.value,
+            page=spec.page.value,
+        )
+    if command == "get-merge-request-commits":
+        return get_merge_request_commits(
+            config,
+            mr_iid=spec.mr_iid.value,
+            project=spec.project.value,
+            per_page=spec.per_page.value,
+            page=spec.page.value,
+        )
+    if command == "get-merge-request-notes":
+        return get_merge_request_notes(
+            config,
+            mr_iid=spec.mr_iid.value,
+            project=spec.project.value,
+            sort=spec.sort.value,
+            per_page=spec.per_page.value,
+            page=spec.page.value,
+        )
+    if command == "get-merge-request-pipelines":
+        return get_merge_request_pipelines(
+            config,
+            mr_iid=spec.mr_iid.value,
+            project=spec.project.value,
+            per_page=spec.per_page.value,
+            page=spec.page.value,
+        )
+    if command == "get-merge-request-conflicts":
+        return get_merge_request_conflicts(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,
+        )
+
+    # ── writes (all autonomy = "confirm") ──
+    if command == "create-issue":
+        return create_issue(
+            config,
+            title=spec.title.value,
+            description=spec.description.value,
+            labels=_list(spec.label),
+            assignees=_list(spec.assignee),
+            milestone_id=spec.milestone_id.value,
+            due_date=spec.due_date.value,
+            confidential=spec.confidential.value,
+            project=spec.project.value,
+        )
+    if command == "update-issue":
+        return update_issue(
+            config,
+            issue_iid=spec.issue_iid.value,
+            title=spec.title.value,
+            description=spec.description.value,
+            add_labels=_list(spec.add_label),
+            remove_labels=_list(spec.remove_label),
+            assignees=_list(spec.assignee),
+            milestone_id=spec.milestone_id.value,
+            due_date=spec.due_date.value,
+            state_event=spec.state.value,
+            project=spec.project.value,
+        )
+    if command == "add-issue-note":
+        return add_issue_note(
+            config,
+            issue_iid=spec.issue_iid.value,
+            body=spec.body.value,
+            internal=spec.internal.value,
+            project=spec.project.value,
+        )
+    if command == "create-merge-request":
+        return create_merge_request(
+            config,
+            source_branch=spec.source_branch.value,
+            target_branch=spec.target_branch.value,
+            title=spec.title.value,
+            description=spec.description.value,
+            draft=spec.draft.value,
+            labels=_list(spec.label),
+            assignees=_list(spec.assignee),
+            reviewers=_list(spec.reviewer),
+            remove_source_branch=spec.remove_source_branch.value,
+            squash=spec.squash.value,
+            project=spec.project.value,
+        )
+    if command == "update-merge-request":
+        return update_merge_request(
+            config,
+            mr_iid=spec.mr_iid.value,
+            title=spec.title.value,
+            description=spec.description.value,
+            target_branch=spec.target_branch.value,
+            add_labels=_list(spec.add_label),
+            remove_labels=_list(spec.remove_label),
+            assignees=_list(spec.assignee),
+            reviewers=_list(spec.reviewer),
+            state_event=spec.state.value,
+            project=spec.project.value,
+        )
+    if command == "add-merge-request-note":
+        return add_merge_request_note(
+            config,
+            mr_iid=spec.mr_iid.value,
+            body=spec.body.value,
+            internal=spec.internal.value,
+            project=spec.project.value,
+        )
+    if command == "merge-merge-request":
+        return merge_merge_request(
+            config,
+            mr_iid=spec.mr_iid.value,
+            sha=spec.sha.value,
+            # An unset flag keeps the merge request's own setting.
+            squash=spec.squash.value or None,
+            remove_source_branch=spec.remove_source_branch.value or None,
+            when_pipeline_succeeds=spec.when_pipeline_succeeds.value,
+            merge_commit_message=spec.merge_commit_message.value,
+            project=spec.project.value,
+        )
+    if command == "create-branch":
+        return create_branch(config, branch=spec.branch.value, ref=spec.ref.value, project=spec.project.value)
+    if command == "write-file":
+        return write_file(
+            config,
+            file_path=spec.file_path.value,
+            content=_content(spec),
+            branch=spec.branch.value,
+            commit_message=spec.commit_message.value,
+            start_branch=spec.start_branch.value,
+            last_commit_id=spec.last_commit_id.value,
+            project=spec.project.value,
+        )
+    if command == "create-pipeline":
+        return create_pipeline(config, ref=spec.ref.value, variables=_list(spec.variable), project=spec.project.value)
+    if command == "retry-pipeline":
+        return retry_pipeline(config, pipeline_id=spec.pipeline_id.value, project=spec.project.value)
+    if command == "cancel-pipeline":
+        return cancel_pipeline(config, pipeline_id=spec.pipeline_id.value, project=spec.project.value)
+    if command == "retry-job":
+        return retry_job(config, job_id=spec.job_id.value, project=spec.project.value)
+    if command == "cancel-job":
+        return cancel_job(config, job_id=spec.job_id.value, project=spec.project.value)
+    if command == "play-job":
+        return play_job(config, job_id=spec.job_id.value, variables=_list(spec.variable), project=spec.project.value)
+
+    # ── deletes (autonomy = "manual": human-only) ──
+    if command == "delete-issue":
+        return delete_issue(config, issue_iid=spec.issue_iid.value, project=spec.project.value)
+    if command == "delete-branch":
+        return delete_branch(config, branch=spec.branch.value, project=spec.project.value)
+    if command == "delete-file":
+        return delete_file(
+            config,
+            file_path=spec.file_path.value,
+            branch=spec.branch.value,
+            commit_message=spec.commit_message.value,
+            last_commit_id=spec.last_commit_id.value,
+            project=spec.project.value,
+        )
+    if command == "delete-pipeline":
+        return delete_pipeline(config, pipeline_id=spec.pipeline_id.value, project=spec.project.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, OSError) as exc:
+        _emit({"error": str(exc), "kind": type(exc).__name__})
+        sys.exit(1)
+    _emit(result)
+
+
+if __name__ == "__main__":
+    main()