pjdev-gitlab 5.1.9__tar.gz → 5.1.12__tar.gz

{pjdev_gitlab-5.1.9 → pjdev_gitlab-5.1.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pjdev-gitlab
-Version: 5.1.9
+Version: 5.1.12
 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
@@ -80,6 +80,51 @@ The OAuth application must be registered as a non-confidential (PKCE) app with
 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).
+
+#### `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

{pjdev_gitlab-5.1.9 → pjdev_gitlab-5.1.12}/README.md

@@ -52,6 +52,51 @@ The OAuth application must be registered as a non-confidential (PKCE) app with
 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).
+
+#### `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

{pjdev_gitlab-5.1.9 → pjdev_gitlab-5.1.12}/pyproject.toml

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

{pjdev_gitlab-5.1.9 → pjdev_gitlab-5.1.12}/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.9"
+__version__ = "5.1.12"

{pjdev_gitlab-5.1.9 → pjdev_gitlab-5.1.12}/src/pjdev_gitlab/__init__.py

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

{pjdev_gitlab-5.1.9 → pjdev_gitlab-5.1.12}/src/pjdev_gitlab/api_utilities.py

@@ -2,7 +2,7 @@ import asyncio
 import ssl
 from contextlib import asynccontextmanager
 from functools import wraps
-from typing import Any, AsyncIterator, Callable, Dict, List, Optional
+from typing import Any, AsyncIterator, Dict, List, Optional
 from urllib.parse import quote
 
 import httpx

pjdev_gitlab-5.1.12/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.12/src/pjdev_gitlab/oauth_cli.py

@@ -0,0 +1,122 @@
+"""Command-line entry point: authenticate to GitLab and print an OAuth token.
+
+Installed as the ``pjdev-gitlab-auth`` console script (see ``[project.scripts]``
+in ``pyproject.toml``). Thin CLI over
+:func:`pjdev_gitlab.oauth_service.get_access_token` that runs the OAuth 2.0
+Authorization Code + PKCE browser flow so API writes are attributed to the human
+invoking it rather than a shared bot. Prints ONLY the access token to stdout;
+status goes to stderr. Tokens are cached + silently refreshed per host under
+``~/.config/pjdev-gitlab/tokens/``, so most runs need no interaction.
+
+The library is instance-agnostic: the OAuth application's client id must be
+supplied per call (there is no built-in default), and the GitLab host defaults to
+``https://gitlab.com``. Callers targeting another instance pass ``--gitlab-url``
+(or ``GL_GITLAB_URL``) and ``--client-id`` (or ``GL_OAUTH_CLIENT_ID``).
+
+Usage::
+
+    pjdev-gitlab-auth --gitlab-url https://gitlab.example.com --client-id <id>
+    # or, equivalently, via the environment:
+    GL_GITLAB_URL=https://gitlab.example.com GL_OAUTH_CLIENT_ID=<id> pjdev-gitlab-auth
+
+The registered OAuth application must be a non-confidential (PKCE) app with the
+requested scope (default ``api``) and Redirect URI exactly
+``http://localhost:<redirect-port>/callback``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from pjdev_gitlab.oauth_service import (
+    DEFAULT_REDIRECT_PORT,
+    DEFAULT_SCOPES,
+    OAuthError,
+    get_access_token,
+)
+
+DEFAULT_GITLAB_URL = "https://gitlab.com"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="pjdev-gitlab-auth",
+        description="Authenticate to GitLab via OAuth and print a short-lived access token.",
+    )
+    parser.add_argument(
+        "--gitlab-url",
+        default=None,
+        help="GitLab base URL (or GL_GITLAB_URL; default https://gitlab.com)",
+    )
+    parser.add_argument(
+        "--client-id",
+        default=None,
+        help="registered OAuth app client id (or GL_OAUTH_CLIENT_ID) -- required",
+    )
+    parser.add_argument(
+        "--client-secret",
+        default=None,
+        help="only for a confidential app (or GL_OAUTH_CLIENT_SECRET)",
+    )
+    parser.add_argument(
+        "--redirect-port",
+        type=int,
+        default=None,
+        help=f"loopback redirect port (or GL_OAUTH_REDIRECT_PORT; default {DEFAULT_REDIRECT_PORT})",
+    )
+    parser.add_argument(
+        "--scopes",
+        default=None,
+        help=f'space-separated scopes (or GL_OAUTH_SCOPES; default "{DEFAULT_SCOPES}")',
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="ignore any cached token and run the browser flow",
+    )
+    args = parser.parse_args()
+
+    gitlab_url = args.gitlab_url or os.environ.get("GL_GITLAB_URL") or DEFAULT_GITLAB_URL
+    client_id = args.client_id or os.environ.get("GL_OAUTH_CLIENT_ID")
+    if not client_id:
+        print(
+            "no OAuth client id: pass --client-id or set GL_OAUTH_CLIENT_ID to the "
+            "registered application's client id.",
+            file=sys.stderr,
+        )
+        return 2
+    client_secret = args.client_secret or os.environ.get("GL_OAUTH_CLIENT_SECRET") or None
+    scopes = args.scopes or os.environ.get("GL_OAUTH_SCOPES") or DEFAULT_SCOPES
+
+    port_raw = (
+        args.redirect_port
+        if args.redirect_port is not None
+        else os.environ.get("GL_OAUTH_REDIRECT_PORT", DEFAULT_REDIRECT_PORT)
+    )
+    try:
+        redirect_port = int(port_raw)
+    except (TypeError, ValueError):
+        print("redirect port must be an integer", file=sys.stderr)
+        return 2
+
+    try:
+        token = get_access_token(
+            gitlab_url=gitlab_url,
+            client_id=client_id,
+            client_secret=client_secret,
+            redirect_port=redirect_port,
+            scopes=scopes,
+            force=args.force,
+        )
+    except OAuthError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    print(token)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())