pjdev-gitlab 5.1.7__tar.gz → 5.1.10__tar.gz

{pjdev_gitlab-5.1.7 → pjdev_gitlab-5.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pjdev-gitlab
-Version: 5.1.7
+Version: 5.1.10
 Project-URL: Documentation, https://gitlab.purplejay.io/keystone/python/-/tree/main/pjdev-gitlab/README.md
 Project-URL: Issues, https://gitlab.purplejay.io/keystone/python/-/issues
 Project-URL: Source, https://gitlab.purplejay.io/keystone/python
@@ -31,7 +31,7 @@ Description-Content-Type: text/markdown
 [![PyPI - Version](https://img.shields.io/pypi/v/pjdev-gitlab.svg)](https://pypi.org/project/pjdev-gitlab)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pjdev-gitlab.svg)](https://pypi.org/project/pjdev-gitlab)
 
-Async GitLab automation SDK. Wraps the GitLab REST API v4 directly with `httpx.AsyncClient` and Pydantic models. Covers issues, merge requests, repository files, and the generic package registry.
+Async GitLab automation SDK. Wraps both the GitLab REST API v4 and GraphQL API directly with `httpx.AsyncClient` and Pydantic models. Covers issues, workItems (the GraphQL replacement for issues — status, comments, labels), merge requests, repository files, and the generic package registry.
 
 -----
 
@@ -48,11 +48,55 @@ via `init()`):
 
 | variable | required | purpose |
 | --- | --- | --- |
-| `GL_TOKEN` | yes | personal/group/project access token (`api` scope) |
+| `GL_TOKEN` | yes | access token (`api` scope) — a PAT, or an OAuth token with `GL_AUTH_SCHEME=bearer` |
 | `GL_GITLAB_URL` | yes | base URL, e.g. `https://gitlab.com` |
+| `GL_AUTH_SCHEME` | no | `private-token` (default, PAT header) or `bearer` (OAuth access token) |
 | `GL_DEFAULT_PROJECT_ID` | no | default project for service helpers |
 | `GL_OUTPUT_PATH` | no | directory for downloaded files |
 
+### OAuth 2.0 (per-user attribution)
+
+To attribute API writes to a real person instead of a shared bot token, mint a
+short-lived OAuth access token with the interactive Authorization Code + PKCE
+flow and initialize with `auth_scheme="bearer"`:
+
+```python
+from pjdev_gitlab import config_service, oauth_service
+
+# Opens a browser for sign-in/consent on first run; caches + refreshes the token
+# per host under ~/.config/pjdev-gitlab/tokens/ (0600) on subsequent runs.
+token = oauth_service.get_access_token(
+    gitlab_url="https://gitlab.example.com",
+    client_id="<registered PKCE app client id>",
+)
+config_service.init(
+    token=token, gitlab_url="https://gitlab.example.com", auth_scheme="bearer"
+)
+```
+
+The OAuth application must be registered as a non-confidential (PKCE) app with
+**scope** `api` and **Redirect URI** exactly `http://localhost:7331/callback`
+(override the port via `get_access_token(redirect_port=...)`). A `bearer` token
+is sent as `Authorization: Bearer <token>`; the default `private-token` scheme
+sends `PRIVATE-TOKEN` for personal/project/group access tokens.
+
+#### `pjdev-gitlab-auth` console script
+
+The same flow is exposed as a console script, so shell callers (e.g. skills) can
+mint a token without embedding any Python. It prints only the token to stdout and
+status to stderr:
+
+```bash
+TOKEN="$(uvx --from 'pjdev-gitlab' pjdev-gitlab-auth \
+  --gitlab-url https://gitlab.example.com --client-id <client-id>)"
+```
+
+The library is instance-agnostic: `--client-id` (or `GL_OAUTH_CLIENT_ID`) is
+required and the host defaults to `https://gitlab.com` (override with
+`--gitlab-url` / `GL_GITLAB_URL`). Other flags: `--client-secret`,
+`--redirect-port`, `--scopes`, `--force` (each with a `GL_OAUTH_*` env
+equivalent).
+
 ### Recommended: 1Password + `op run`
 
 On a developer laptop, keep the token in 1Password and inject it into the host
@@ -120,9 +164,51 @@ asyncio.run(main())
 
 Run it: `op run --env-file=.env.op -- python my_script.py`.
 
+### WorkItems (GraphQL)
+
+`workItem` is GitLab's unified replacement for the legacy `Issue` type — use
+`work_items_service` for status/comments/labels on modern GitLab instances:
+
+```python
+import asyncio
+from pjdev_gitlab import config_service, work_items_service
+from pjdev_gitlab.models import WorkItemState, WorkItemStateEvent
+
+async def main() -> None:
+    config_service.init()
+
+    open_bugs = await work_items_service.search_work_items(
+        project_path="my-group/my-project",
+        state=WorkItemState.OPEN,
+        labels=["bug"],
+        search="timeout",
+    )
+
+    label = await work_items_service.create_label(
+        "needs-review", project_path="my-group/my-project", color="#FFAA00"
+    )
+    await work_items_service.set_work_item_labels(
+        open_bugs[0].iid,
+        [label.id],
+        mode="add",
+        project_path="my-group/my-project",
+    )
+    await work_items_service.comment_on_work_item(
+        open_bugs[0].iid,
+        "Triaged — assigning a reviewer.",
+        project_path="my-group/my-project",
+    )
+    await work_items_service.set_work_item_state(
+        open_bugs[0].iid, WorkItemStateEvent.CLOSE,
+        project_path="my-group/my-project",
+    )
+
+asyncio.run(main())
+```
+
 ## Bundled agent skills
 
-Skill files for AI agents ship under `.agents/skills/` inside the installed package, following the [library-skills.io](https://library-skills.io/create/) convention. Topics: issues, merge requests, repository files, generic packages.
+Skill files for AI agents ship under `.agents/skills/` inside the installed package, following the [library-skills.io](https://library-skills.io/create/) convention. Topics: issues, workItems, merge requests, repository files, generic packages.
 
 ## License
 

pjdev_gitlab-5.1.10/README.md

@@ -0,0 +1,187 @@
+# pjdev-gitlab
+
+[![PyPI - Version](https://img.shields.io/pypi/v/pjdev-gitlab.svg)](https://pypi.org/project/pjdev-gitlab)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pjdev-gitlab.svg)](https://pypi.org/project/pjdev-gitlab)
+
+Async GitLab automation SDK. Wraps both the GitLab REST API v4 and GraphQL API directly with `httpx.AsyncClient` and Pydantic models. Covers issues, workItems (the GraphQL replacement for issues — status, comments, labels), merge requests, repository files, and the generic package registry.
+
+-----
+
+## Installation
+
+```console
+pip install pjdev-gitlab
+```
+
+## Configuration
+
+`pjdev-gitlab` reads `GL_*` environment variables (or accepts the same values
+via `init()`):
+
+| variable | required | purpose |
+| --- | --- | --- |
+| `GL_TOKEN` | yes | access token (`api` scope) — a PAT, or an OAuth token with `GL_AUTH_SCHEME=bearer` |
+| `GL_GITLAB_URL` | yes | base URL, e.g. `https://gitlab.com` |
+| `GL_AUTH_SCHEME` | no | `private-token` (default, PAT header) or `bearer` (OAuth access token) |
+| `GL_DEFAULT_PROJECT_ID` | no | default project for service helpers |
+| `GL_OUTPUT_PATH` | no | directory for downloaded files |
+
+### OAuth 2.0 (per-user attribution)
+
+To attribute API writes to a real person instead of a shared bot token, mint a
+short-lived OAuth access token with the interactive Authorization Code + PKCE
+flow and initialize with `auth_scheme="bearer"`:
+
+```python
+from pjdev_gitlab import config_service, oauth_service
+
+# Opens a browser for sign-in/consent on first run; caches + refreshes the token
+# per host under ~/.config/pjdev-gitlab/tokens/ (0600) on subsequent runs.
+token = oauth_service.get_access_token(
+    gitlab_url="https://gitlab.example.com",
+    client_id="<registered PKCE app client id>",
+)
+config_service.init(
+    token=token, gitlab_url="https://gitlab.example.com", auth_scheme="bearer"
+)
+```
+
+The OAuth application must be registered as a non-confidential (PKCE) app with
+**scope** `api` and **Redirect URI** exactly `http://localhost:7331/callback`
+(override the port via `get_access_token(redirect_port=...)`). A `bearer` token
+is sent as `Authorization: Bearer <token>`; the default `private-token` scheme
+sends `PRIVATE-TOKEN` for personal/project/group access tokens.
+
+#### `pjdev-gitlab-auth` console script
+
+The same flow is exposed as a console script, so shell callers (e.g. skills) can
+mint a token without embedding any Python. It prints only the token to stdout and
+status to stderr:
+
+```bash
+TOKEN="$(uvx --from 'pjdev-gitlab' pjdev-gitlab-auth \
+  --gitlab-url https://gitlab.example.com --client-id <client-id>)"
+```
+
+The library is instance-agnostic: `--client-id` (or `GL_OAUTH_CLIENT_ID`) is
+required and the host defaults to `https://gitlab.com` (override with
+`--gitlab-url` / `GL_GITLAB_URL`). Other flags: `--client-secret`,
+`--redirect-port`, `--scopes`, `--force` (each with a `GL_OAUTH_*` env
+equivalent).
+
+### Recommended: 1Password + `op run`
+
+On a developer laptop, keep the token in 1Password and inject it into the host
+process with [`op run`](https://developer.1password.com/docs/cli/secrets-environment-variables/) —
+the secret never sits in your shell environment or on disk in plaintext.
+
+1. Install the 1Password CLI (`brew install --cask 1password-cli`) and turn on
+   **Settings → Developer → Integrate with 1Password CLI** in the desktop app.
+2. Store the token in 1Password (e.g. an API Credential titled
+   `GitLab — purplejay` with a `credential` field).
+3. Drop a committable `.env.op` next to your project — references only, no
+   real secrets:
+
+   ```bash
+   # .env.op
+   GL_TOKEN="op://Private/GitLab — purplejay/credential"
+   GL_GITLAB_URL="https://gitlab.purplejay.io"
+   ```
+
+4. Launch your script — or the entire Claude Code session that will use this
+   library — under `op run`:
+
+   ```bash
+   op run --env-file=.env.op -- python my_script.py
+   op run --env-file=.env.op -- claude
+   ```
+
+`op run` resolves the references, exports them to the subprocess, and tears
+them down on exit. Inside Python, just call `config_service.init()` with no
+arguments and the values flow in from the environment.
+
+In CI, skip 1Password and set `GL_TOKEN`/`GL_GITLAB_URL` from the job's
+existing variables (e.g. `CI_JOB_TOKEN` for project-scoped operations).
+
+## Usage
+
+```python
+import asyncio
+from pjdev_gitlab import config_service, issues_service
+from pjdev_gitlab.models import StateEvent
+
+async def main() -> None:
+    # Token & URL come from GL_TOKEN / GL_GITLAB_URL (e.g. via `op run`).
+    config_service.init(default_project_id="my-group/my-project")
+
+    issue = await issues_service.create_issue(
+        project_id="my-group/my-project",
+        title="Bug: timeout on /widgets",
+        description="The endpoint times out under load.\n\n/label ~bug ~priority::high",
+        labels=["bug"],
+    )
+    await issues_service.comment_on_issue(
+        project_id="my-group/my-project",
+        issue_iid=issue.iid,
+        body="Investigating now.",
+    )
+    await issues_service.set_issue_state(
+        project_id="my-group/my-project",
+        issue_iid=issue.iid,
+        state_event=StateEvent.close,
+    )
+
+asyncio.run(main())
+```
+
+Run it: `op run --env-file=.env.op -- python my_script.py`.
+
+### WorkItems (GraphQL)
+
+`workItem` is GitLab's unified replacement for the legacy `Issue` type — use
+`work_items_service` for status/comments/labels on modern GitLab instances:
+
+```python
+import asyncio
+from pjdev_gitlab import config_service, work_items_service
+from pjdev_gitlab.models import WorkItemState, WorkItemStateEvent
+
+async def main() -> None:
+    config_service.init()
+
+    open_bugs = await work_items_service.search_work_items(
+        project_path="my-group/my-project",
+        state=WorkItemState.OPEN,
+        labels=["bug"],
+        search="timeout",
+    )
+
+    label = await work_items_service.create_label(
+        "needs-review", project_path="my-group/my-project", color="#FFAA00"
+    )
+    await work_items_service.set_work_item_labels(
+        open_bugs[0].iid,
+        [label.id],
+        mode="add",
+        project_path="my-group/my-project",
+    )
+    await work_items_service.comment_on_work_item(
+        open_bugs[0].iid,
+        "Triaged — assigning a reviewer.",
+        project_path="my-group/my-project",
+    )
+    await work_items_service.set_work_item_state(
+        open_bugs[0].iid, WorkItemStateEvent.CLOSE,
+        project_path="my-group/my-project",
+    )
+
+asyncio.run(main())
+```
+
+## Bundled agent skills
+
+Skill files for AI agents ship under `.agents/skills/` inside the installed package, following the [library-skills.io](https://library-skills.io/create/) convention. Topics: issues, workItems, merge requests, repository files, generic packages.
+
+## License
+
+`pjdev-gitlab` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

{pjdev_gitlab-5.1.7 → pjdev_gitlab-5.1.10}/pyproject.toml

@@ -27,6 +27,9 @@ dependencies = [
   "pydantic>=2.12.5",
 ]
 
+[project.scripts]
+pjdev-gitlab-auth = "pjdev_gitlab.oauth_cli:main"
+
 [project.optional-dependencies]
 dev = [
     "ruff",

pjdev_gitlab-5.1.10/src/pjdev_gitlab/.agents/skills/pjdev_gitlab_work_items/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: pjdev_gitlab_work_items
+description: Use this skill to automate GitLab workItems via pjdev-gitlab — the GraphQL-backed successor to issues. Covers searching/filtering by project or group with pagination, viewing/updating status, reading/posting/replying to comments, and managing labels (including creating new project or group labels). Trigger when the user asks to query, create, or modify GitLab workItems (or "issues" on a recent GitLab instance) programmatically.
+---
+
+# pjdev_gitlab_work_items
+
+Async helpers for GitLab workItems, built on `httpx.AsyncClient` against the
+[GitLab GraphQL API](https://docs.gitlab.com/api/graphql/).
+
+`workItem` is GitLab's unified replacement for the legacy `Issue` type. New
+behavior (custom statuses, hierarchy, the typed-issuable system) lives on
+workItems and is only reachable via GraphQL. Use this module instead of
+`issues_service` when working on a modern GitLab instance.
+
+Reference docs (source of truth for behavior):
+- [GraphQL API](https://docs.gitlab.com/api/graphql/)
+- [GraphQL reference](https://docs.gitlab.com/api/graphql/reference/)
+- [WorkItems](https://docs.gitlab.com/user/work_items/)
+- [Labels](https://docs.gitlab.com/user/project/labels/)
+- [Comments and threads](https://docs.gitlab.com/user/discussions/)
+
+## Setup
+
+`pjdev_gitlab` reads `GL_TOKEN` and `GL_GITLAB_URL` from the environment.
+Recommended pattern: keep the token in 1Password and inject it with
+[`op run`](https://developer.1password.com/docs/cli/secrets-environment-variables/).
+
+```bash
+# .env.op
+GL_TOKEN="op://Private/GitLab — <host>/credential"
+GL_GITLAB_URL="https://gitlab.example.com"
+```
+
+```bash
+op run --env-file=.env.op -- python my_script.py
+```
+
+```python
+from pjdev_gitlab import config_service, work_items_service
+
+config_service.init()  # token/url from env
+```
+
+The token needs `api` scope (mutations) or at least `read_api` (queries only).
+
+## Identifiers
+
+Every workItem-facing helper accepts either:
+
+- A **Global ID** like `gid://gitlab/WorkItem/12345`.
+- A **numeric DB id** (`12345`), which is auto-coerced to a Global ID.
+- A project/group-scoped **iid** (the number users see in the URL) plus
+  `project_path=...` or `group_path=...` — the helper resolves it to a
+  Global ID with one extra query.
+
+Pick whichever you have on hand:
+
+```python
+# By iid (common when scripting against URLs the user shared)
+item = await work_items_service.get_work_item(42, project_path="group/proj")
+
+# By Global ID (zero-lookup path)
+item = await work_items_service.get_work_item("gid://gitlab/WorkItem/12345")
+```
+
+## Search & filter
+
+`search_work_items` walks the namespace's `workItems` connection and follows
+`pageInfo.endCursor` until exhausted (set `paginate_results=False` for a
+single page). Either `project_path` or `group_path` is required.
+
+```python
+from pjdev_gitlab.models import WorkItemState
+
+open_bugs = await work_items_service.search_work_items(
+    project_path="group/proj",
+    state=WorkItemState.OPEN,
+    labels=["bug"],
+    search="timeout",  # matches title/description
+)
+
+across_group = await work_items_service.search_work_items(
+    group_path="group",
+    state=WorkItemState.OPEN,
+    page_size=50,
+)
+```
+
+## View / update status
+
+```python
+from pjdev_gitlab.models import WorkItemStateEvent
+
+item = await work_items_service.get_work_item(42, project_path="group/proj")
+print(item.state)  # WorkItemState.OPEN | CLOSED
+
+await work_items_service.set_work_item_state(
+    42, WorkItemStateEvent.CLOSE, project_path="group/proj"
+)
+```
+
+## Comments and threaded replies
+
+```python
+# Read all human comments (system notes filtered out by default)
+notes = await work_items_service.list_work_item_notes(
+    42, project_path="group/proj"
+)
+for n in notes:
+    print(n.author.username if n.author else "?", "->", n.body)
+
+# Post a new top-level comment (starts a new discussion thread)
+await work_items_service.comment_on_work_item(
+    42, "Looking into this now.", project_path="group/proj"
+)
+
+# Reply to an existing thread
+discussions = await work_items_service.list_work_item_discussions(
+    42, project_path="group/proj"
+)
+await work_items_service.reply_to_work_item_discussion(
+    42,
+    discussion_id=discussions[0].id,
+    body="Confirmed — pushing a fix shortly.",
+    project_path="group/proj",
+)
+```
+
+## Manage labels
+
+Label management uses a **delta API** — add or remove specific labels. There
+is no "replace" mode; compute the diff yourself if you need one.
+
+```python
+# Look up labels (includes parent group labels for projects)
+labels = await work_items_service.list_labels(
+    project_path="group/proj", search="prio"
+)
+# [ProjectLabel(id='gid://gitlab/ProjectLabel/7', title='priority::high', ...), ...]
+
+# Apply / remove on a workItem
+await work_items_service.set_work_item_labels(
+    42, [labels[0].id], mode="add", project_path="group/proj"
+)
+await work_items_service.set_work_item_labels(
+    42, [labels[0].id], mode="remove", project_path="group/proj"
+)
+
+# Create a brand-new project label
+new_label = await work_items_service.create_label(
+    "needs-review",
+    project_path="group/proj",
+    color="#FFAA00",
+    description="Awaiting reviewer triage",
+)
+```
+
+Group labels (visible to all child projects) are created the same way with
+`group_path=` instead of `project_path=`.
+
+## Tips for AI agents
+
+- Prefer batching label changes into one `set_work_item_labels(mode="add", labels=[a, b, c])`
+  call — that's one mutation instead of three.
+- When you only have an iid, pass `project_path=` once and reuse the
+  `WorkItem.id` (Global ID) on follow-up mutations to skip the lookup round-trip.
+- `WorkItem.state` is `OPEN`/`CLOSED` (uppercase, matches the GraphQL enum
+  directly), but the **filter** uses lowercase `opened`/`closed` — the helper
+  translates `WorkItemState.OPEN` automatically when you pass it to
+  `search_work_items(state=...)`.
+- A workItem returned by a mutation always reflects the post-mutation state,
+  so you can read `result.state` / `result.labels` instead of re-fetching.

{pjdev_gitlab-5.1.7 → pjdev_gitlab-5.1.10}/src/pjdev_gitlab/__about__.py

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

{pjdev_gitlab-5.1.7 → pjdev_gitlab-5.1.10}/src/pjdev_gitlab/__init__.py

@@ -12,6 +12,9 @@ __all__ = [
     "issues_service",
     "merge_requests_service",
     "models",
+    "oauth_cli",
+    "oauth_service",
     "packages_service",
     "repo_files_service",
+    "work_items_service",
 ]