pjdev-gitlab 5.0.0__py3-none-any.whl

pjdev_gitlab/.agents/skills/pjdev_gitlab_issues/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: pjdev_gitlab_issues
+description: Use this skill to automate GitLab issues via pjdev-gitlab — search/analytics, create issues with markdown and inline images, post comments and threaded discussions, and change state, labels, iteration, or milestone. Trigger when the user asks to query, create, or modify GitLab issues programmatically.
+---
+
+# pjdev_gitlab_issues
+
+Async helpers for GitLab issue automation, built on `httpx.AsyncClient` against the [GitLab REST API v4](https://docs.gitlab.com/api/issues/).
+
+Reference docs (source of truth for behavior):
+- [Issues](https://docs.gitlab.com/user/project/issues/)
+- [Comments and threads](https://docs.gitlab.com/user/discussions/)
+- [Labels](https://docs.gitlab.com/user/project/labels/)
+- [Iterations](https://docs.gitlab.com/user/group/iterations/)
+- [Milestones](https://docs.gitlab.com/user/project/milestones/)
+- [Quick actions](https://docs.gitlab.com/user/project/quick_actions/)
+- [GitLab Flavored Markdown](https://docs.gitlab.com/user/markdown/)
+
+## Setup
+
+`pjdev_gitlab` reads `GL_TOKEN` and `GL_GITLAB_URL` from the environment. The
+recommended pattern is to keep the token in 1Password and inject it into the
+host process with [`op run`](https://developer.1password.com/docs/cli/secrets-environment-variables/),
+so the secret never sits in your shell environment or on disk in plaintext.
+
+1. Store the token in 1Password (e.g. an API Credential titled `GitLab — <host>`
+   with a `credential` field).
+2. In the project that uses this skill, create a committable `.env.op` with
+   1Password references — no real secrets:
+
+   ```bash
+   # .env.op
+   GL_TOKEN="op://Private/GitLab — <host>/credential"
+   GL_GITLAB_URL="https://gitlab.example.com"
+   ```
+
+3. Launch the host process (the script, or the entire Claude Code session)
+   under `op run`:
+
+   ```bash
+   op run --env-file=.env.op -- python my_script.py
+   op run --env-file=.env.op -- claude
+   ```
+
+Then call `config_service.init()` with no arguments — it picks up `GL_*` from env:
+
+```python
+from pjdev_gitlab import config_service, issues_service
+
+config_service.init(default_project_id="my-group/my-project")  # token/url from env
+```
+
+For tests or one-off scripts you can still pass values explicitly:
+
+```python
+config_service.init(token="glpat-xxx", gitlab_url="https://gitlab.com")
+```
+
+The token needs `api` scope. Project-scoped tokens work for project-only
+operations; iterations live at group level, so use a group/personal token for
+`list_iterations`.
+
+## Search & analytics
+
+```python
+from pjdev_gitlab import issues_service
+from pjdev_gitlab.models import IssueState
+
+open_bugs = await issues_service.search_issues(
+    "my-group/my-project",
+    state=IssueState.opened,
+    labels=["bug"],
+    created_after="2026-01-01T00:00:00Z",
+)
+
+by_label = await issues_service.aggregate_issues(
+    "my-group/my-project", group_by="label", state=IssueState.opened
+)
+# {"bug": 12, "frontend": 7, ...}
+```
+
+`search_issues` paginates by default. Set `paginate_results=False` for a single page.
+
+## Create with markdown and inline images
+
+`<img src="...">` tags in the description are replaced positionally with the markdown
+returned by GitLab's upload endpoint. Quick actions in the description (e.g. `/label`,
+`/assign`) are processed by GitLab server-side.
+
+```python
+from pathlib import Path
+
+issue = await issues_service.create_issue(
+    "my-group/my-project",
+    title="Bug: timeout on /widgets",
+    description=(
+        "Repro:\n"
+        "1. Open page\n"
+        '2. <img src="placeholder1">\n\n'
+        "/label ~bug ~priority::high\n"
+        "/assign @me"
+    ),
+    image_paths=[Path("./screenshot.png")],
+    labels=["bug"],
+)
+```
+
+## Comment vs. threaded discussion
+
+Single comment:
+
+```python
+await issues_service.comment_on_issue(
+    "my-group/my-project", issue_iid=42, body="Investigating now."
+)
+```
+
+Threaded discussion (use this when subsequent replies should belong to the same thread):
+
+```python
+discussion = await issues_service.start_issue_discussion(
+    "my-group/my-project", issue_iid=42, body="Root-cause analysis"
+)
+```
+
+## Change state, labels, iteration, milestone
+
+```python
+from pjdev_gitlab.models import StateEvent
+
+await issues_service.set_issue_state("my-group/my-project", 42, StateEvent.close)
+await issues_service.set_issue_labels(
+    "my-group/my-project", 42, ["regression"], mode="add"
+)
+await issues_service.set_issue_iteration("my-group/my-project", 42, iteration_id=17)
+await issues_service.set_issue_milestone("my-group/my-project", 42, milestone_id=5)
+```
+
+Iterations and milestones can be discovered with `list_iterations(group_id)` and
+`list_milestones(project_id)`.
+
+## Tips for AI agents
+
+- Prefer quick actions (`/label`, `/assign`, `/iteration *iteration:42`, `/close`)
+  inside the description or comment body instead of multiple API calls — this is
+  one round-trip and matches how humans use GitLab.
+- IIDs (`issue.iid`) are project-scoped and what users see; IDs (`issue.id`) are
+  GitLab-global. Always use IIDs for issue endpoints.
+- Project IDs may be numeric (`12345`) or namespaced paths (`group/sub/project`).
+  Both work; the helpers URL-encode them automatically.

pjdev_gitlab/.agents/skills/pjdev_gitlab_merge_requests/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: pjdev_gitlab_merge_requests
+description: Use this skill to automate GitLab merge request review with pjdev-gitlab — list/get MRs, fetch diffs/changes, post flat or threaded inline-diff comments, and approve/unapprove. Trigger when the user wants to review, comment on, or approve GitLab merge requests programmatically.
+---
+
+# pjdev_gitlab_merge_requests
+
+Async helpers for GitLab merge request automation against the [Merge Requests API](https://docs.gitlab.com/api/merge_requests/) and [Discussions API](https://docs.gitlab.com/api/discussions/).
+
+Reference docs:
+- [Merge requests](https://docs.gitlab.com/user/project/merge_requests/)
+- [Comments and threads](https://docs.gitlab.com/user/discussions/)
+
+## Setup
+
+`pjdev_gitlab` reads `GL_TOKEN` and `GL_GITLAB_URL` from the environment.
+The recommended pattern is 1Password + [`op run`](https://developer.1password.com/docs/cli/secrets-environment-variables/) — the token stays in your vault and is injected only into the host process.
+
+```bash
+# .env.op (committable — references only)
+GL_TOKEN="op://Private/GitLab — <host>/credential"
+GL_GITLAB_URL="https://gitlab.example.com"
+```
+
+Launch the script or Claude Code session under `op run`:
+
+```bash
+op run --env-file=.env.op -- python my_script.py
+op run --env-file=.env.op -- claude
+```
+
+Then in code:
+
+```python
+from pjdev_gitlab import config_service
+config_service.init()  # GL_TOKEN / GL_GITLAB_URL come from env
+```
+
+For tests or quick scripts, pass values explicitly: `config_service.init(token="glpat-xxx", gitlab_url="https://gitlab.com")`.
+
+## List and inspect
+
+```python
+from pjdev_gitlab import merge_requests_service
+from pjdev_gitlab.models import MergeRequestState
+
+open_mrs = await merge_requests_service.list_merge_requests(
+    "my-group/my-project", state=MergeRequestState.opened
+)
+mr = await merge_requests_service.get_merge_request("my-group/my-project", 88)
+changes = await merge_requests_service.get_merge_request_changes(
+    "my-group/my-project", 88
+)
+# changes["changes"] is a list of {old_path, new_path, diff, ...}
+# changes["diff_refs"] has base_sha / start_sha / head_sha needed for inline comments
+```
+
+## Flat comment (un-threaded)
+
+```python
+await merge_requests_service.comment_on_merge_request(
+    "my-group/my-project", 88, "Looks good — one nit on naming."
+)
+```
+
+## Threaded inline-diff comment
+
+Use the `diff_refs` from `get_merge_request` (or `get_merge_request_changes`) to position the comment on a specific line of a specific file.
+
+```python
+mr = await merge_requests_service.get_merge_request("my-group/my-project", 88)
+refs = mr.diff_refs  # {"base_sha": ..., "start_sha": ..., "head_sha": ...}
+
+await merge_requests_service.comment_on_merge_request_diff(
+    "my-group/my-project",
+    mr_iid=88,
+    body="Consider extracting this into a helper.",
+    base_sha=refs["base_sha"],
+    start_sha=refs["start_sha"],
+    head_sha=refs["head_sha"],
+    new_path="src/pjdev_gitlab/issues_service.py",
+    new_line=42,
+)
+```
+
+## Approve / unapprove
+
+```python
+await merge_requests_service.approve_merge_request("my-group/my-project", 88)
+await merge_requests_service.unapprove_merge_request("my-group/my-project", 88)
+```
+
+## Tips for AI agents
+
+- A typical review loop is: `get_merge_request_changes` → analyze diff → for each
+  finding, `comment_on_merge_request_diff` (threaded inline) → optional summary
+  via `comment_on_merge_request` (flat).
+- Inline diff comments on **deleted** lines need `old_path` + `old_line`; on
+  **added** lines need `new_path` + `new_line`. Pass both when commenting on a
+  context line.
+- `mr.iid` (project-scoped) is what URLs and humans use — always pass `iid`, not `id`.

pjdev_gitlab/.agents/skills/pjdev_gitlab_packages/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: pjdev_gitlab_packages
+description: Use this skill to publish, download, or list artifacts in the GitLab generic package registry via pjdev-gitlab. Trigger when the user wants to upload build artifacts, retrieve a previously-published file, or enumerate packages in a project.
+---
+
+# pjdev_gitlab_packages
+
+Async helpers for the [GitLab generic package registry](https://docs.gitlab.com/user/packages/generic_packages/).
+
+## Setup
+
+`pjdev_gitlab` reads `GL_TOKEN` and `GL_GITLAB_URL` from the environment.
+The recommended pattern on a developer laptop is 1Password + [`op run`](https://developer.1password.com/docs/cli/secrets-environment-variables/) — the token stays in your vault and is injected only into the host process.
+
+```bash
+# .env.op (committable — references only)
+GL_TOKEN="op://Private/GitLab — <host>/credential"
+GL_GITLAB_URL="https://gitlab.example.com"
+```
+
+Launch the script or Claude Code session under `op run`:
+
+```bash
+op run --env-file=.env.op -- python publish.py
+```
+
+Then in code:
+
+```python
+from pjdev_gitlab import config_service
+config_service.init()  # GL_TOKEN / GL_GITLAB_URL come from env
+```
+
+The token must have `api` scope. In GitLab CI, skip 1Password and rely on
+`CI_JOB_TOKEN` (set `GL_TOKEN=$CI_JOB_TOKEN` in the job) — the project's
+package-registry permissions of the running pipeline apply automatically.
+
+## Upload
+
+```python
+from pathlib import Path
+from pjdev_gitlab import packages_service
+
+result = await packages_service.upload_generic_package(
+    project_id="my-group/my-project",
+    package_name="my-tool",
+    package_version="1.4.0",
+    file_name="my-tool-1.4.0.tar.gz",
+    file_path=Path("./dist/my-tool-1.4.0.tar.gz"),
+)
+```
+
+`status="hidden"` keeps the package out of the UI listing (useful for staging
+a release before flipping it to default).
+
+## Download
+
+```python
+path = await packages_service.download_generic_package(
+    project_id="my-group/my-project",
+    package_name="my-tool",
+    package_version="1.4.0",
+    file_name="my-tool-1.4.0.tar.gz",
+    dest=Path("./out/my-tool-1.4.0.tar.gz"),
+)
+```
+
+## List
+
+```python
+packages = await packages_service.list_packages(
+    project_id="my-group/my-project", package_type="generic"
+)
+```
+
+## Tips for AI agents
+
+- File names are URL-encoded for you. Use the literal upload filename.
+- The same `(name, version, file_name)` triple is upsert: re-uploading
+  overwrites unless the project's "Reject duplicate uploads" setting blocks it.
+- For very large files, prefer streaming uploads at the HTTP layer; this helper
+  reads the whole file into memory because the generic-package endpoint expects
+  the body to be the raw file content.

pjdev_gitlab/.agents/skills/pjdev_gitlab_repo_files/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: pjdev_gitlab_repo_files
+description: Use this skill to fetch a single file or recursively download a directory from a GitLab repository at a specific ref via pjdev-gitlab. Trigger when the user wants to read repo content, download files, or mirror a subtree without cloning the repo.
+---
+
+# pjdev_gitlab_repo_files
+
+Async helpers for reading repository content via the [GitLab Repositories API](https://docs.gitlab.com/api/repositories/) and [Repository Files API](https://docs.gitlab.com/api/repository_files/) — without cloning the repo.
+
+Reference docs:
+- [Repositories](https://docs.gitlab.com/user/project/repository/)
+
+## Setup
+
+`pjdev_gitlab` reads `GL_TOKEN` and `GL_GITLAB_URL` from the environment.
+The recommended pattern is 1Password + [`op run`](https://developer.1password.com/docs/cli/secrets-environment-variables/) — the token stays in your vault and is injected only into the host process.
+
+```bash
+# .env.op (committable — references only)
+GL_TOKEN="op://Private/GitLab — <host>/credential"
+GL_GITLAB_URL="https://gitlab.example.com"
+GL_OUTPUT_PATH="./downloads"  # optional default for downloads
+```
+
+Launch the script or Claude Code session under `op run`:
+
+```bash
+op run --env-file=.env.op -- python my_script.py
+```
+
+Then in code:
+
+```python
+from pjdev_gitlab import config_service
+config_service.init()  # GL_TOKEN / GL_GITLAB_URL / GL_OUTPUT_PATH come from env
+```
+
+For tests or quick scripts, pass values explicitly: `config_service.init(token="glpat-xxx", gitlab_url="https://gitlab.com", output_path=Path("./downloads"))`.
+
+## Get a single file
+
+```python
+from pjdev_gitlab import repo_files_service
+
+# Decoded text
+readme = await repo_files_service.get_file(
+    "my-group/my-project", "README.md", ref="main"
+)
+
+# Raw bytes (e.g. for binaries)
+raw = await repo_files_service.get_file(
+    "my-group/my-project", "assets/logo.png", ref="main", decode=False
+)
+```
+
+## Download a single file to disk
+
+```python
+path = await repo_files_service.download_file(
+    "my-group/my-project",
+    file_path="docs/spec.pdf",
+    ref="v1.4.0",
+    dest=Path("./out/spec.pdf"),  # falls back to config.output_path if omitted
+)
+```
+
+## List a tree (paginated, optionally recursive)
+
+```python
+entries = await repo_files_service.list_tree(
+    "my-group/my-project", path="docs", ref="main", recursive=True
+)
+# Each entry: id, name, type ("blob" | "tree"), path, mode
+```
+
+## Download an entire directory
+
+Walks the tree recursively and downloads every blob, preserving relative paths.
+
+```python
+await repo_files_service.download_directory(
+    "my-group/my-project",
+    path="docs",
+    ref="main",
+    dest=Path("./out/docs"),
+)
+```
+
+## Tips for AI agents
+
+- File paths are URL-encoded automatically (`docs/spec.pdf` -> `docs%2Fspec.pdf`),
+  so just pass the literal repo path.
+- `ref` accepts branches, tags, and full commit SHAs. Pin to a SHA if you need
+  reproducibility.
+- For very large repos, `download_directory` issues one HTTP request per blob.
+  Use `recursive=True` on `list_tree` first to size the work.

pjdev_gitlab/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2026-present Chris O'Neill <chris@purplejay.io>
+#
+# SPDX-License-Identifier: MIT
+__version__ = "5.0.0"

pjdev_gitlab/__init__.py

@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: 2026-present Chris O'Neill <chris@purplejay.io>
+#
+# SPDX-License-Identifier: MIT
+
+from loguru import logger
+
+logger.disable("pjdev_gitlab")
+
+__all__ = [
+    "api_utilities",
+    "config_service",
+    "issues_service",
+    "merge_requests_service",
+    "models",
+    "packages_service",
+    "repo_files_service",
+]

pjdev_gitlab/api_utilities.py

@@ -0,0 +1,201 @@
+import asyncio
+import ssl
+from contextlib import asynccontextmanager
+from functools import wraps
+from typing import Any, AsyncIterator, Callable, Dict, List, Optional
+from urllib.parse import quote
+
+import httpx
+from httpx import ConnectError, HTTPStatusError
+from loguru import logger
+
+from pjdev_gitlab.config_service import get_config
+
+
+def encode_path_segment(value: Any) -> str:
+    """URL-encode a path segment (e.g. project id 'group/sub/project' -> 'group%2Fsub%2Fproject')."""
+    return quote(str(value), safe="")
+
+
+class GitlabTokenAuth(httpx.Auth):
+    def __init__(self, token: str) -> None:
+        self.token = token
+
+    def auth_flow(self, request):
+        request.headers["PRIVATE-TOKEN"] = self.token
+        yield request
+
+
+async def log_request_headers(request: httpx.Request) -> None:
+    logger.debug(f"Request: {request.method} {request.url}")
+
+
+async def log_response_headers(response: httpx.Response) -> None:
+    logger.debug(
+        f"Response: {response.request.method} {response.request.url} -> {response.status_code}"
+    )
+
+
+def get_http_client() -> httpx.AsyncClient:
+    config = get_config()
+    if not config.token:
+        raise ValueError("GitLab token is not configured -- set GL_TOKEN or pass token=...")
+
+    return httpx.AsyncClient(
+        base_url=config.api_base_url,
+        auth=GitlabTokenAuth(config.token),
+        verify=ssl.create_default_context(),
+        timeout=config.request_timeout_seconds,
+        event_hooks={
+            "request": [log_request_headers],
+            "response": [log_response_headers],
+        },
+    )
+
+
+@asynccontextmanager
+async def http_client() -> AsyncIterator[httpx.AsyncClient]:
+    async with get_http_client() as _client:
+        yield _client
+
+
+def async_retry_http(
+    default_value: Optional[Any] = None,
+    status_codes_to_ignore: Optional[List[int]] = None,
+):
+    """Async retry decorator with exponential backoff.
+
+    Mirrors `pjdev_sn_sdk.api_utilities.async_retry_http`. Aborts immediately on listed
+    status codes (typically 4xx) so we don't hammer the API on permanent failures.
+    """
+
+    def decorator(func):
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            config = get_config()
+            max_attempts = config.http_retry_max_count
+            delay_seconds = config.http_retry_delay_seconds
+            attempts = 0
+            exceptions: List[BaseException] = []
+
+            while attempts < max_attempts:
+                try:
+                    return await func(*args, **kwargs)
+                except HTTPStatusError as e:
+                    logger.warning(f"{e.response.status_code}: {e.response.reason_phrase}")
+                    logger.warning(e.response.text)
+                    exceptions.append(e)
+                    if (
+                        status_codes_to_ignore
+                        and e.response.status_code in status_codes_to_ignore
+                    ):
+                        break
+                except ConnectError as e:
+                    logger.warning(f"{e.request.url} not reachable")
+                    exceptions.append(e)
+                except Exception as e:
+                    logger.warning("unexpected exception")
+                    logger.warning(e)
+                    exceptions.append(e)
+                    break
+
+                attempts += 1
+                if attempts == max_attempts:
+                    break
+                total_delay = delay_seconds**attempts
+                logger.warning(
+                    f"Attempt {attempts}/{max_attempts} failed. Retrying in {total_delay}s..."
+                )
+                await asyncio.sleep(total_delay)
+
+            if default_value is None:
+                raise ExceptionGroup(f"Failed after {max_attempts} attempts", exceptions)
+            logger.error(f"Failed after {max_attempts} attempts")
+            return default_value
+
+        return wrapper
+
+    return decorator
+
+
+async def paginate(
+    client: httpx.AsyncClient,
+    url: str,
+    params: Optional[Dict[str, Any]] = None,
+    page_size: int = 100,
+) -> List[Dict[str, Any]]:
+    """Paginate a GitLab list endpoint following the X-Next-Page header.
+
+    GitLab returns ``X-Next-Page`` (empty when no more pages) and ``X-Total`` /
+    ``X-Total-Pages`` for offset-paginated endpoints. Some endpoints only support
+    keyset pagination, but the offset/page params are still accepted as a fallback.
+    """
+    request_params: Dict[str, Any] = {**(params or {}), "per_page": page_size, "page": 1}
+    results: List[Dict[str, Any]] = []
+
+    while True:
+        response = await client.get(url, params=request_params)
+        response.raise_for_status()
+        page = response.json()
+        if not isinstance(page, list):
+            raise ValueError(f"expected list response from {url}, got {type(page).__name__}")
+        results.extend(page)
+        next_page = response.headers.get("X-Next-Page", "").strip()
+        if not next_page:
+            break
+        try:
+            request_params["page"] = int(next_page)
+        except ValueError:
+            logger.warning(f"could not parse X-Next-Page={next_page!r}")
+            break
+
+    return results
+
+
+def get_error_message(eg: ExceptionGroup) -> str:
+    parts: List[str] = []
+    for e in eg.exceptions:
+        if isinstance(e, httpx.HTTPStatusError):
+            parts.append(f"{e.response.status_code} -> {e.response.text}")
+        else:
+            parts.append(str(e))
+    message = " | ".join(parts)
+    logger.error(message)
+    return message
+
+
+__upload_sem = asyncio.Semaphore(10)
+
+
+async def upload_to_project(
+    project_id: Any,
+    filepath: Any,
+    *,
+    filename: Optional[str] = None,
+    client: Optional[httpx.AsyncClient] = None,
+) -> Dict[str, Any]:
+    """Upload a file to a project's uploads endpoint and return the GitLab response.
+
+    The response includes a ``markdown`` field (e.g. ``![alt](/uploads/.../foo.png)``)
+    that callers can splice into issue/MR/comment bodies.
+    """
+    from pathlib import Path
+
+    path = Path(filepath)
+    final_name = filename or path.name
+
+    async def _exec(_client: httpx.AsyncClient) -> Dict[str, Any]:
+        async with __upload_sem:
+            with open(path, "rb") as fh:
+                files = {"file": (final_name, fh.read())}
+                r = await _client.post(
+                    f"/projects/{encode_path_segment(project_id)}/uploads",
+                    files=files,
+                )
+            r.raise_for_status()
+            return r.json()
+
+    if client is None:
+        async with http_client() as _client:
+            return await _exec(_client)
+    return await _exec(client)