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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pjdev-gitlab
-Version: 5.1.10
+Version: 5.1.13
 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
@@ -97,6 +97,34 @@ required and the host defaults to `https://gitlab.com` (override with
 `--redirect-port`, `--scopes`, `--force` (each with a `GL_OAUTH_*` env
 equivalent).
 
+#### `pjdev-gitlab-sync` console script
+
+`pjdev-gitlab-sync` clones a repo over HTTPS using an OAuth token, or
+fast-forwards it if it is already present — **no SSH key setup required**. It is
+deterministic and idempotent: the *same* command both installs a repo the first
+time and pulls updates on every later run, so it is the one thing a non-technical
+user has to remember.
+
+```bash
+pjdev-gitlab-sync developers/claude-skills \
+  --gitlab-url https://gitlab.example.com \
+  --client-id <client-id> \
+  --target ~/git/claude-skills      # optional; defaults to the repo basename
+```
+
+It mints/reuses the token via the same PKCE flow as `pjdev-gitlab-auth` (opening
+a browser only when there is no valid cached token), then hands it to git through
+`GIT_ASKPASS`. The token is therefore **never** written to `.git/config`, placed
+on a git command line, or cached in a system keychain — the stored `origin`
+remote is always a plain, tokenless HTTPS URL you can safely inspect. The
+resolved checkout path is printed to stdout (so it is scriptable, e.g.
+`cd "$(pjdev-gitlab-sync group/name)"`); status goes to stderr.
+
+Updates are `merge --ff-only`: if the checkout has diverging local commits, the
+command fails loudly rather than discarding your work. Flags mirror
+`pjdev-gitlab-auth` plus `--target` (`GL_SYNC_TARGET`) and `--branch`
+(`GL_SYNC_BRANCH`); the repo path may also come from `GL_REPO`.
+
 ### Recommended: 1Password + `op run`
 
 On a developer laptop, keep the token in 1Password and inject it into the host
@@ -206,6 +234,31 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+#### Custom statuses
+
+The workflow status an instance defines for itself (`Ready`, `In progress`, ...)
+is neither a label nor the open/closed `state`, and REST does not expose it.
+Reading it is opt-in, because GitLab ships the status widget as an experiment
+(**17.11+**) and selecting it against an older instance fails the whole query:
+
+```python
+# Just the status — one small query. Preferred on a hot path.
+status = await work_items_service.get_work_item_status(
+    42, project_path="my-group/my-project"
+)
+print(status.name if status else "no status set")
+
+# Or folded into a read you were making anyway.
+item = await work_items_service.get_work_item(
+    42, project_path="my-group/my-project", include_status=True
+)
+items = await work_items_service.search_work_items(
+    project_path="my-group/my-project", include_status=True
+)
+```
+
+Status names are configured per namespace — match them case-insensitively.
+
 ## 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.

{pjdev_gitlab-5.1.10 → pjdev_gitlab-5.1.13}/README.md

@@ -69,6 +69,34 @@ required and the host defaults to `https://gitlab.com` (override with
 `--redirect-port`, `--scopes`, `--force` (each with a `GL_OAUTH_*` env
 equivalent).
 
+#### `pjdev-gitlab-sync` console script
+
+`pjdev-gitlab-sync` clones a repo over HTTPS using an OAuth token, or
+fast-forwards it if it is already present — **no SSH key setup required**. It is
+deterministic and idempotent: the *same* command both installs a repo the first
+time and pulls updates on every later run, so it is the one thing a non-technical
+user has to remember.
+
+```bash
+pjdev-gitlab-sync developers/claude-skills \
+  --gitlab-url https://gitlab.example.com \
+  --client-id <client-id> \
+  --target ~/git/claude-skills      # optional; defaults to the repo basename
+```
+
+It mints/reuses the token via the same PKCE flow as `pjdev-gitlab-auth` (opening
+a browser only when there is no valid cached token), then hands it to git through
+`GIT_ASKPASS`. The token is therefore **never** written to `.git/config`, placed
+on a git command line, or cached in a system keychain — the stored `origin`
+remote is always a plain, tokenless HTTPS URL you can safely inspect. The
+resolved checkout path is printed to stdout (so it is scriptable, e.g.
+`cd "$(pjdev-gitlab-sync group/name)"`); status goes to stderr.
+
+Updates are `merge --ff-only`: if the checkout has diverging local commits, the
+command fails loudly rather than discarding your work. Flags mirror
+`pjdev-gitlab-auth` plus `--target` (`GL_SYNC_TARGET`) and `--branch`
+(`GL_SYNC_BRANCH`); the repo path may also come from `GL_REPO`.
+
 ### Recommended: 1Password + `op run`
 
 On a developer laptop, keep the token in 1Password and inject it into the host
@@ -178,6 +206,31 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+#### Custom statuses
+
+The workflow status an instance defines for itself (`Ready`, `In progress`, ...)
+is neither a label nor the open/closed `state`, and REST does not expose it.
+Reading it is opt-in, because GitLab ships the status widget as an experiment
+(**17.11+**) and selecting it against an older instance fails the whole query:
+
+```python
+# Just the status — one small query. Preferred on a hot path.
+status = await work_items_service.get_work_item_status(
+    42, project_path="my-group/my-project"
+)
+print(status.name if status else "no status set")
+
+# Or folded into a read you were making anyway.
+item = await work_items_service.get_work_item(
+    42, project_path="my-group/my-project", include_status=True
+)
+items = await work_items_service.search_work_items(
+    project_path="my-group/my-project", include_status=True
+)
+```
+
+Status names are configured per namespace — match them case-insensitively.
+
 ## 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.

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

@@ -29,6 +29,7 @@ dependencies = [
 
 [project.scripts]
 pjdev-gitlab-auth = "pjdev_gitlab.oauth_cli:main"
+pjdev-gitlab-sync = "pjdev_gitlab.sync_cli:main"
 
 [project.optional-dependencies]
 dev = [

{pjdev_gitlab-5.1.10 → pjdev_gitlab-5.1.13}/src/pjdev_gitlab/.agents/skills/pjdev_gitlab_work_items/SKILL.md

@@ -87,7 +87,7 @@ across_group = await work_items_service.search_work_items(
 )
 ```
 
-## View / update status
+## Open/closed state
 
 ```python
 from pjdev_gitlab.models import WorkItemStateEvent
@@ -100,6 +100,39 @@ await work_items_service.set_work_item_state(
 )
 ```
 
+## Custom status
+
+Separate from open/closed: the workflow status an instance defines for itself
+(`Ready`, `In progress`, `Code Complete`, ...). It is **not** a label, and the
+REST API does not expose it at all — GraphQL's status widget is the only way to
+read it.
+
+Reading it is opt-in, because the widget is a GitLab *experiment* introduced in
+**17.11**: selecting it against an older instance fails the entire query, so it
+is never requested unless asked for.
+
+```python
+# Just the status — one small query, no discussions dragged along.
+# This is the right call on a hot path (e.g. per webhook event).
+status = await work_items_service.get_work_item_status(42, project_path="group/proj")
+print(status.name if status else "no status set")
+
+# Or alongside everything else, when you were fetching the item anyway.
+item = await work_items_service.get_work_item(
+    42, project_path="group/proj", include_status=True
+)
+print(item.status.name if item.status else "no status set")
+
+# Also available on searches.
+items = await work_items_service.search_work_items(
+    project_path="group/proj", include_status=True
+)
+```
+
+`None` means the item has no status assigned. Status names are configured per
+namespace, so **match them case-insensitively** rather than hard-coding an enum —
+`"Code Complete"` on one instance may be `"code complete"` on another.
+
 ## Comments and threaded replies
 
 ```python

{pjdev_gitlab-5.1.10 → pjdev_gitlab-5.1.13}/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.10"
+__version__ = "5.1.13"

pjdev_gitlab-5.1.13/src/pjdev_gitlab/git_sync_service.py

@@ -0,0 +1,286 @@
+"""Clone or update a GitLab repo over HTTPS using a short-lived OAuth token.
+
+Deterministic, idempotent counterpart to the interactive auth flow: given an
+OAuth access token (see :func:`pjdev_gitlab.oauth_service.get_access_token`),
+clone the repo when the target directory does not yet exist, or fast-forward it
+when it does. Running the same command again is always safe -- it is the single
+operation a non-technical user needs both to *install* and to *update* a repo.
+
+The token is handed to git through ``GIT_ASKPASS`` (the token itself is passed to
+the helper via an environment variable, never on a command line), so it never
+lands in ``.git/config``, in git's argv, or in a system credential store. The
+stored ``origin`` remote is therefore always a plain, tokenless HTTPS URL that
+anyone can safely inspect -- and, because it is HTTPS rather than SSH, no SSH key
+setup is required.
+
+Updates use ``merge --ff-only``: if the checkout has diverging local commits or
+uncommitted changes that would be clobbered, the command fails loudly rather than
+discarding the user's work.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import stat
+import subprocess  # noqa: S404 - invoking git is the entire point of this module
+import sys
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Optional, Sequence
+
+StatusFn = Callable[[str], None]
+
+# GitLab requires the literal username ``oauth2`` when using an OAuth token as
+# HTTPS basic-auth; an ``Authorization: Bearer`` header does NOT work for
+# git-over-HTTPS, only this basic-auth form does.
+OAUTH2_USER = "oauth2"
+
+# Name of the env var the generated askpass helper reads the token from, so the
+# token is never written into the helper script or onto any command line.
+_TOKEN_ENV = "PJDEV_GITLAB_SYNC_TOKEN"
+
+
+class SyncError(RuntimeError):
+    """Raised when the clone/update cannot complete."""
+
+
+def _default_status(msg: str) -> None:
+    print(msg, file=sys.stderr)
+
+
+# A git runner: run ``git <args>`` in ``cwd`` with ``env``, returning captured
+# stdout and raising SyncError on a non-zero exit. Injectable so tests need no
+# real git or network.
+GitRunner = Callable[..., str]
+
+
+@dataclass(frozen=True)
+class SyncResult:
+    """Outcome of a :func:`sync_repo` call."""
+
+    action: str  # "cloned" or "updated"
+    path: Path  # absolute path to the checkout
+    remote_url: str  # tokenless HTTPS URL stored as origin
+
+
+# --------------------------------------------------------------------------- #
+# URL / path helpers (pure)
+# --------------------------------------------------------------------------- #
+def build_remote_url(gitlab_url: str, repo_path: str) -> str:
+    """Return the plain, tokenless HTTPS clone URL for ``repo_path``.
+
+    ``repo_path`` is a ``group/subgroup/name`` path; a trailing ``.git`` and
+    surrounding slashes are tolerated.
+    """
+    base = gitlab_url.strip().rstrip("/")
+    path = repo_path.strip().strip("/")
+    if path.endswith(".git"):
+        path = path[:-4]
+    if not path:
+        raise SyncError("repo path is empty")
+    return f"{base}/{path}.git"
+
+
+def _authed_url(remote_url: str) -> str:
+    """Insert the ``oauth2`` username into ``remote_url`` (no token -- that comes
+    from the askpass helper)."""
+    scheme, _, rest = remote_url.partition("://")
+    if not rest:
+        raise SyncError(f"remote url is not absolute: {remote_url}")
+    return f"{scheme}://{OAUTH2_USER}@{rest}"
+
+
+def default_target_dir(repo_path: str) -> Path:
+    """Default checkout directory: the repo's basename in the current directory."""
+    name = repo_path.strip().strip("/").rsplit("/", 1)[-1]
+    if name.endswith(".git"):
+        name = name[:-4]
+    if not name:
+        raise SyncError("could not derive a target directory from the repo path")
+    return Path(name)
+
+
+# --------------------------------------------------------------------------- #
+# git invocation
+# --------------------------------------------------------------------------- #
+def run_git(
+    args: Sequence[str],
+    *,
+    cwd: Optional[Path] = None,
+    env: Optional[dict[str, str]] = None,
+) -> str:
+    """Run ``git <args>`` (credential helpers disabled), returning its stdout.
+
+    ``-c credential.helper=`` blanks any configured helper so our ``GIT_ASKPASS``
+    is the only credential source and nothing gets cached into a system keychain.
+    Raises :class:`SyncError` on a non-zero exit.
+    """
+    full = ["git", "-c", "credential.helper=", *args]
+    proc = subprocess.run(  # noqa: S603 - args are internally constructed, not user shell
+        full,
+        cwd=str(cwd) if cwd is not None else None,
+        env=env,
+        capture_output=True,
+        text=True,
+    )
+    if proc.returncode != 0:
+        detail = (proc.stderr or proc.stdout or "").strip()
+        raise SyncError(f"`git {' '.join(args)}` failed ({proc.returncode}): {detail}")
+    return proc.stdout
+
+
+def _write_askpass(dir_path: Path) -> Path:
+    """Write a POSIX askpass helper that echoes the token from the environment.
+
+    The username is supplied in the URL, so git only ever asks for the password;
+    the helper unconditionally returns the token read from ``_TOKEN_ENV``.
+    """
+    script = dir_path / "askpass.sh"
+    script.write_text(f'#!/bin/sh\nprintf "%s" "${_TOKEN_ENV}"\n')
+    script.chmod(stat.S_IRWXU)  # 0700
+    return script
+
+
+def _current_branch(runner: GitRunner, target: Path) -> str:
+    """Return the branch currently checked out in ``target``.
+
+    Raises :class:`SyncError` on a detached HEAD, where there is no branch to
+    fast-forward and the caller must pass ``--branch`` explicitly.
+    """
+    try:
+        out = runner(["symbolic-ref", "--short", "HEAD"], cwd=target)
+    except SyncError as exc:
+        raise SyncError(
+            f"{target} is not on a branch (detached HEAD); "
+            "pass --branch to choose one to fast-forward"
+        ) from exc
+    branch = (out or "").strip()
+    if not branch:
+        raise SyncError(
+            f"{target} is not on a branch (detached HEAD); "
+            "pass --branch to choose one to fast-forward"
+        )
+    return branch
+
+
+def _local_branch_exists(runner: GitRunner, target: Path, branch: str) -> bool:
+    """Whether ``branch`` already exists as a local branch in ``target``."""
+    try:
+        runner(["rev-parse", "--verify", "--quiet", f"refs/heads/{branch}"], cwd=target)
+        return True
+    except SyncError:
+        return False
+
+
+def _ensure_origin(runner: GitRunner, target: Path, remote_url: str) -> None:
+    """Point ``origin`` at the tokenless ``remote_url``, adding it if absent.
+
+    A fresh clone always has an ``origin``, but a pre-existing checkout adopted
+    by this tool might have none (or one named differently), so create the remote
+    rather than fail an update that has already succeeded.
+    """
+    try:
+        runner(["remote", "get-url", "origin"], cwd=target)
+    except SyncError:
+        runner(["remote", "add", "origin", remote_url], cwd=target)
+    else:
+        runner(["remote", "set-url", "origin", remote_url], cwd=target)
+
+
+# --------------------------------------------------------------------------- #
+# Public entry point
+# --------------------------------------------------------------------------- #
+def sync_repo(
+    *,
+    gitlab_url: str,
+    repo_path: str,
+    token: str,
+    target_dir: Optional[os.PathLike[str] | str] = None,
+    branch: Optional[str] = None,
+    on_status: Optional[StatusFn] = None,
+    runner: GitRunner = run_git,
+) -> SyncResult:
+    """Clone ``repo_path`` if absent, else fast-forward the existing checkout.
+
+    Returns a :class:`SyncResult`. Raises :class:`SyncError` on any failure,
+    including a fast-forward that would clobber local work.
+    """
+    if not token:
+        raise SyncError("an OAuth access token is required")
+    status = on_status or _default_status
+    remote_url = build_remote_url(gitlab_url, repo_path)
+    authed_url = _authed_url(remote_url)
+
+    target = Path(target_dir).expanduser() if target_dir else default_target_dir(repo_path)
+    target = target.absolute()
+
+    if target.exists():
+        if not (target / ".git").is_dir():
+            raise SyncError(
+                f"{target} already exists but is not a git repository; "
+                "choose a different target directory"
+            )
+        action = "updated"
+    else:
+        action = "cloned"
+
+    # Sensitive git operations (clone/fetch) run with this env; the token is
+    # reachable only via the askpass helper, never on a command line.
+    askpass_dir = Path(tempfile.mkdtemp(prefix="pjdev-gitlab-sync-"))
+    try:
+        askpass_dir.chmod(stat.S_IRWXU)  # 0700
+        askpass = _write_askpass(askpass_dir)
+        env = dict(os.environ)
+        env["GIT_ASKPASS"] = str(askpass)
+        env["GIT_TERMINAL_PROMPT"] = "0"  # never fall back to an interactive prompt
+        env[_TOKEN_ENV] = token
+
+        if action == "cloned":
+            status(f"Cloning {remote_url} into {target} ...")
+            target.parent.mkdir(parents=True, exist_ok=True)
+            clone_args = ["clone"]
+            if branch:
+                clone_args += ["--branch", branch]
+            clone_args += [authed_url, str(target)]
+            try:
+                runner(clone_args, env=env)
+            except SyncError:
+                # A failed clone can leave a partial target dir behind. Since
+                # this call created it, remove it so a re-run starts clean
+                # instead of tripping the "exists but not a git repo" guard.
+                shutil.rmtree(target, ignore_errors=True)
+                raise
+        else:
+            status(f"Updating {target} from {remote_url} ...")
+            # Fast-forward the branch the caller asked for, or -- when none is
+            # given -- the one actually checked out (NOT the remote's default,
+            # which is what a bare `fetch` + `FETCH_HEAD` would pick up once the
+            # user has switched branches). Fetch that branch by name over the raw
+            # URL so FETCH_HEAD is exactly it (no named remote, no tracking refs).
+            sync_branch = branch or _current_branch(runner, target)
+            runner(["fetch", authed_url, sync_branch], cwd=target, env=env)
+            if branch and not _local_branch_exists(runner, target, branch):
+                # First time this checkout sees the branch: create it at the
+                # fetched tip. Safe -- there is no local history to clobber.
+                runner(["checkout", "-b", branch, "FETCH_HEAD"], cwd=target, env=env)
+            else:
+                # Make sure the branch is checked out, then fast-forward it.
+                # --ff-only refuses to clobber diverging local commits.
+                runner(["checkout", sync_branch], cwd=target, env=env)
+                runner(["merge", "--ff-only", "FETCH_HEAD"], cwd=target, env=env)
+    finally:
+        # Best-effort cleanup of the transient askpass helper.
+        try:
+            for child in askpass_dir.iterdir():
+                child.unlink()
+            askpass_dir.rmdir()
+        except OSError:
+            pass
+
+    # Guarantee origin is the plain, tokenless (and username-less) HTTPS URL.
+    _ensure_origin(runner, target, remote_url)
+
+    status(f"{action.capitalize()} {target}")
+    return SyncResult(action=action, path=target, remote_url=remote_url)

{pjdev_gitlab-5.1.10 → pjdev_gitlab-5.1.13}/src/pjdev_gitlab/models.py

@@ -265,6 +265,32 @@ class WorkItemIteration(GraphQLBase):
     web_url: Optional[str] = None
 
 
+class WorkItemStatus(GraphQLBase):
+    """A custom work-item status (``Ready``, ``In progress``, ``Code Complete``, ...).
+
+    Distinct from :class:`WorkItemState`, which is only ``OPEN``/``CLOSED``.
+    Statuses are defined per namespace, so the names are whatever the instance's
+    administrators configured — match them case-insensitively rather than
+    hard-coding an enum.
+
+    GitLab exposes this as an **experiment** (``WorkItemWidgetStatus``,
+    introduced in 17.11), which is why the widget is opt-in throughout
+    :mod:`pjdev_gitlab.work_items_service` — see ``include_status``. ``category``
+    and ``description`` are 18.1+ and are deliberately not selected, so the
+    queries here stay valid against 17.11.
+
+    Every field is optional: an instance may return a status object before it has
+    been fully configured, and a parse failure here would take down the whole
+    work-item read.
+    """
+
+    id: Optional[str] = None
+    name: Optional[str] = None
+    icon_name: Optional[str] = None
+    color: Optional[str] = None
+    position: Optional[int] = None
+
+
 class WorkItemNote(GraphQLBase):
     id: str
     body: str
@@ -316,6 +342,9 @@ class WorkItem(GraphQLBase):
     start_date: Optional[str] = None
     due_date: Optional[str] = None
     discussions: List[WorkItemDiscussion] = []
+    status: Optional[WorkItemStatus] = None
+    """Only populated when the read requested ``include_status=True``; ``None``
+    otherwise, which is indistinguishable from "this item has no status set"."""
 
     widgets: List[Dict[str, Any]] = []
 
@@ -345,6 +374,11 @@ class WorkItem(GraphQLBase):
             elif widget_type == "START_AND_DUE_DATE":
                 flat["start_date"] = widget.get("startDate")
                 flat["due_date"] = widget.get("dueDate")
+            elif widget_type == "STATUS":
+                # Only present when the query opted in via include_status; a work
+                # item with no status assigned still sends the widget, with a
+                # null status.
+                flat["status"] = widget.get("status")
             elif widget_type == "NOTES":
                 nodes = (widget.get("discussions") or {}).get("nodes") or []
                 flat["discussions"] = [