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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pjdev-gitlab
-Version: 5.1.10
+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
@@ -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

{pjdev_gitlab-5.1.10 → pjdev_gitlab-5.1.12}/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

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

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/sync_cli.py

@@ -0,0 +1,164 @@
+"""Command-line entry point: clone or update a GitLab repo over OAuth HTTPS.
+
+Installed as the ``pjdev-gitlab-sync`` console script (see ``[project.scripts]``
+in ``pyproject.toml``). It mints (or reuses) an OAuth token via the same PKCE
+flow as ``pjdev-gitlab-auth`` and then hands it to
+:func:`pjdev_gitlab.git_sync_service.sync_repo`, which clones the repo the first
+time and fast-forwards it on every subsequent run. This is the one command a
+non-technical user needs to *install* a repo and to *get updates* -- no SSH key
+setup and no token handling required.
+
+The stored ``origin`` remote is always a plain, tokenless HTTPS URL. The
+resolved checkout path is printed to stdout (so it is scriptable, e.g.
+``cd "$(pjdev-gitlab-sync group/name)"``); all status goes to stderr.
+
+Usage::
+
+    pjdev-gitlab-sync group/subgroup/name \\
+      --gitlab-url https://gitlab.example.com --client-id <id> [--target DIR]
+
+Like ``pjdev-gitlab-auth``, the host defaults to ``https://gitlab.com`` and every
+flag has a ``GL_*`` environment equivalent.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from pjdev_gitlab.git_sync_service import SyncError, sync_repo
+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-sync",
+        description=(
+            "Clone or update a GitLab repo over HTTPS using an OAuth token "
+            "(no SSH key needed). Safe to re-run: clones once, fast-forwards after."
+        ),
+    )
+    parser.add_argument(
+        "repo",
+        nargs="?",
+        default=None,
+        help="repo path 'group/subgroup/name' (or GL_REPO) -- required",
+    )
+    parser.add_argument(
+        "--target",
+        default=None,
+        help="directory to clone/update into (or GL_SYNC_TARGET; "
+        "default: the repo basename in the current directory)",
+    )
+    parser.add_argument(
+        "--branch",
+        default=None,
+        help="branch to check out and fast-forward (or GL_SYNC_BRANCH; "
+        "default: the repo's default branch)",
+    )
+    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 sign-in flow",
+    )
+    args = parser.parse_args()
+
+    repo = args.repo or os.environ.get("GL_REPO")
+    if not repo:
+        print(
+            "no repo: pass a 'group/subgroup/name' path or set GL_REPO.",
+            file=sys.stderr,
+        )
+        return 2
+
+    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
+    target = args.target or os.environ.get("GL_SYNC_TARGET") or None
+    branch = args.branch or os.environ.get("GL_SYNC_BRANCH") or None
+
+    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
+
+    try:
+        result = sync_repo(
+            gitlab_url=gitlab_url,
+            repo_path=repo,
+            token=token,
+            target_dir=target,
+            branch=branch,
+        )
+    except SyncError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    # stdout: just the path, so the command is scriptable.
+    print(result.path)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{pjdev_gitlab-5.1.10 → pjdev_gitlab-5.1.12}/test_report_pjdev-gitlab.txt

@@ -3,72 +3,98 @@ platform linux -- Python 3.12.3, pytest-9.1.1, pluggy-1.6.0 -- /venv/bin/python3
 cachedir: .pytest_cache
 rootdir: /builds/keystone/python/pjdev-gitlab
 configfile: pyproject.toml
-plugins: asyncio-1.4.0, respx-0.23.1, anyio-4.14.1
+plugins: asyncio-1.4.0, respx-0.23.1, anyio-4.14.2
 asyncio: mode=Mode.AUTO, debug=False, asyncio_default_fixture_loop_scope=None, asyncio_default_test_loop_scope=function
-collecting ... collected 63 items
+collecting ... collected 89 items
 
 tests/tests_for_api_utilities.py::test_build_auth_defaults_to_private_token PASSED [  1%]
-tests/tests_for_api_utilities.py::test_build_auth_selects_bearer_for_oauth PASSED [  3%]
-tests/tests_for_api_utilities.py::test_bearer_scheme_sends_authorization_header PASSED [  4%]
-tests/tests_for_api_utilities.py::test_encode_path_segment PASSED        [  6%]
-tests/tests_for_api_utilities.py::test_paginate_consumes_x_next_page PASSED [  7%]
-tests/tests_for_api_utilities.py::test_async_retry_http_aborts_on_ignored_status PASSED [  9%]
-tests/tests_for_api_utilities.py::test_async_retry_http_retries_on_5xx PASSED [ 11%]
-tests/tests_for_api_utilities.py::test_upload_to_project_returns_markdown PASSED [ 12%]
-tests/tests_for_issues_service.py::test_search_issues_paginates PASSED   [ 14%]
-tests/tests_for_issues_service.py::test_create_issue_with_image_uploads_first_then_creates PASSED [ 15%]
-tests/tests_for_issues_service.py::test_set_issue_state PASSED           [ 17%]
-tests/tests_for_issues_service.py::test_set_issue_labels_modes PASSED    [ 19%]
-tests/tests_for_issues_service.py::test_aggregate_issues_by_label PASSED [ 20%]
-tests/tests_for_issues_service.py::test_comment_on_issue PASSED          [ 22%]
-tests/tests_for_merge_requests_service.py::test_get_merge_request PASSED [ 23%]
-tests/tests_for_merge_requests_service.py::test_comment_on_merge_request PASSED [ 25%]
-tests/tests_for_merge_requests_service.py::test_inline_diff_comment_payload_shape PASSED [ 26%]
-tests/tests_for_merge_requests_service.py::test_approve_and_unapprove PASSED [ 28%]
-tests/tests_for_models.py::test_config_api_base_url_strips_trailing_slash PASSED [ 30%]
-tests/tests_for_models.py::test_issue_extra_fields_ignored PASSED        [ 31%]
-tests/tests_for_models.py::test_merge_request_basic PASSED               [ 33%]
-tests/tests_for_models.py::test_config_env_loading PASSED                [ 34%]
-tests/tests_for_oauth_cli.py::test_missing_client_id_errors PASSED       [ 36%]
-tests/tests_for_oauth_cli.py::test_success_prints_only_token PASSED      [ 38%]
-tests/tests_for_oauth_cli.py::test_reads_config_from_env PASSED          [ 39%]
-tests/tests_for_oauth_cli.py::test_bad_redirect_port_errors PASSED       [ 41%]
-tests/tests_for_oauth_cli.py::test_oauth_error_returns_one PASSED        [ 42%]
-tests/tests_for_oauth_service.py::test_make_pkce_challenge_is_s256_of_verifier PASSED [ 44%]
-tests/tests_for_oauth_service.py::test_cache_path_is_per_host_and_private PASSED [ 46%]
-tests/tests_for_oauth_service.py::test_token_if_valid_expiry PASSED      [ 47%]
-tests/tests_for_oauth_service.py::test_store_token_response_roundtrip PASSED [ 49%]
-tests/tests_for_oauth_service.py::test_store_token_response_requires_access_token PASSED [ 50%]
-tests/tests_for_oauth_service.py::test_refresh_access_token_success PASSED [ 52%]
-tests/tests_for_oauth_service.py::test_refresh_access_token_returns_none_on_error PASSED [ 53%]
-tests/tests_for_oauth_service.py::test_get_access_token_reuses_valid_cache PASSED [ 55%]
-tests/tests_for_oauth_service.py::test_get_access_token_refreshes_expired_cache PASSED [ 57%]
-tests/tests_for_oauth_service.py::test_get_access_token_requires_client_id PASSED [ 58%]
-tests/tests_for_packages_service.py::test_upload_generic_package_url_shape PASSED [ 60%]
-tests/tests_for_packages_service.py::test_download_generic_package PASSED [ 61%]
-tests/tests_for_packages_service.py::test_list_packages PASSED           [ 63%]
-tests/tests_for_repo_files_service.py::test_get_file_url_encoded PASSED  [ 65%]
-tests/tests_for_repo_files_service.py::test_download_file_writes_to_dest PASSED [ 66%]
-tests/tests_for_repo_files_service.py::test_download_directory_walks_tree PASSED [ 68%]
-tests/tests_for_work_items_service.py::test_make_work_item_gid_passthrough_and_coerce PASSED [ 69%]
-tests/tests_for_work_items_service.py::test_work_item_from_node_flattens_widgets PASSED [ 71%]
-tests/tests_for_work_items_service.py::test_graphql_raises_on_errors PASSED [ 73%]
-tests/tests_for_work_items_service.py::test_paginate_graphql_follows_end_cursor PASSED [ 74%]
-tests/tests_for_work_items_service.py::test_get_work_item_by_global_id PASSED [ 76%]
-tests/tests_for_work_items_service.py::test_get_work_item_by_project_path_and_iid_uses_namespace_lookup PASSED [ 77%]
-tests/tests_for_work_items_service.py::test_get_work_item_missing_raises PASSED [ 79%]
-tests/tests_for_work_items_service.py::test_search_work_items_paginates_and_translates_state PASSED [ 80%]
-tests/tests_for_work_items_service.py::test_search_work_items_group_scope_uses_group_field PASSED [ 82%]
-tests/tests_for_work_items_service.py::test_search_work_items_requires_one_scope PASSED [ 84%]
-tests/tests_for_work_items_service.py::test_set_work_item_state_closes_via_workItemUpdate PASSED [ 85%]
-tests/tests_for_work_items_service.py::test_set_work_item_state_mutation_errors_raise PASSED [ 87%]
-tests/tests_for_work_items_service.py::test_list_work_item_notes_filters_system_notes PASSED [ 88%]
-tests/tests_for_work_items_service.py::test_comment_on_work_item_creates_note PASSED [ 90%]
-tests/tests_for_work_items_service.py::test_reply_to_work_item_discussion_threads_via_discussion_id PASSED [ 92%]
-tests/tests_for_work_items_service.py::test_set_work_item_labels_add_passes_addLabelIds PASSED [ 93%]
-tests/tests_for_work_items_service.py::test_set_work_item_labels_remove_passes_removeLabelIds PASSED [ 95%]
-tests/tests_for_work_items_service.py::test_list_labels_for_project_includes_ancestor_groups PASSED [ 96%]
+tests/tests_for_api_utilities.py::test_build_auth_selects_bearer_for_oauth PASSED [  2%]
+tests/tests_for_api_utilities.py::test_bearer_scheme_sends_authorization_header PASSED [  3%]
+tests/tests_for_api_utilities.py::test_encode_path_segment PASSED        [  4%]
+tests/tests_for_api_utilities.py::test_paginate_consumes_x_next_page PASSED [  5%]
+tests/tests_for_api_utilities.py::test_async_retry_http_aborts_on_ignored_status PASSED [  6%]
+tests/tests_for_api_utilities.py::test_async_retry_http_retries_on_5xx PASSED [  7%]
+tests/tests_for_api_utilities.py::test_upload_to_project_returns_markdown PASSED [  8%]
+tests/tests_for_git_sync_service.py::test_build_remote_url[https://gitlab.example.com-g/s/n-https://gitlab.example.com/g/s/n.git] PASSED [ 10%]
+tests/tests_for_git_sync_service.py::test_build_remote_url[https://gitlab.example.com/-/g/n/-https://gitlab.example.com/g/n.git] PASSED [ 11%]
+tests/tests_for_git_sync_service.py::test_build_remote_url[https://gitlab.example.com-g/n.git-https://gitlab.example.com/g/n.git] PASSED [ 12%]
+tests/tests_for_git_sync_service.py::test_build_remote_url_empty_repo_errors PASSED [ 13%]
+tests/tests_for_git_sync_service.py::test_default_target_dir[developers/claude-skills-claude-skills] PASSED [ 14%]
+tests/tests_for_git_sync_service.py::test_default_target_dir[g/s/name.git-name] PASSED [ 15%]
+tests/tests_for_git_sync_service.py::test_default_target_dir[solo-solo] PASSED [ 16%]
+tests/tests_for_git_sync_service.py::test_clone_when_target_missing PASSED [ 17%]
+tests/tests_for_git_sync_service.py::test_clone_passes_token_via_askpass_env_only PASSED [ 19%]
+tests/tests_for_git_sync_service.py::test_clone_with_branch PASSED       [ 20%]
+tests/tests_for_git_sync_service.py::test_update_when_target_is_repo PASSED [ 21%]
+tests/tests_for_git_sync_service.py::test_update_with_existing_branch_checks_out_and_ff PASSED [ 22%]
+tests/tests_for_git_sync_service.py::test_update_with_new_branch_creates_from_fetch_head PASSED [ 23%]
+tests/tests_for_git_sync_service.py::test_update_adds_origin_when_absent PASSED [ 24%]
+tests/tests_for_git_sync_service.py::test_update_detached_head_errors PASSED [ 25%]
+tests/tests_for_git_sync_service.py::test_clone_failure_removes_partial_target PASSED [ 26%]
+tests/tests_for_git_sync_service.py::test_target_exists_but_not_a_repo_errors PASSED [ 28%]
+tests/tests_for_git_sync_service.py::test_missing_token_errors PASSED    [ 29%]
+tests/tests_for_git_sync_service.py::test_ff_only_failure_propagates PASSED [ 30%]
+tests/tests_for_issues_service.py::test_search_issues_paginates PASSED   [ 31%]
+tests/tests_for_issues_service.py::test_create_issue_with_image_uploads_first_then_creates PASSED [ 32%]
+tests/tests_for_issues_service.py::test_set_issue_state PASSED           [ 33%]
+tests/tests_for_issues_service.py::test_set_issue_labels_modes PASSED    [ 34%]
+tests/tests_for_issues_service.py::test_aggregate_issues_by_label PASSED [ 35%]
+tests/tests_for_issues_service.py::test_comment_on_issue PASSED          [ 37%]
+tests/tests_for_merge_requests_service.py::test_get_merge_request PASSED [ 38%]
+tests/tests_for_merge_requests_service.py::test_comment_on_merge_request PASSED [ 39%]
+tests/tests_for_merge_requests_service.py::test_inline_diff_comment_payload_shape PASSED [ 40%]
+tests/tests_for_merge_requests_service.py::test_approve_and_unapprove PASSED [ 41%]
+tests/tests_for_models.py::test_config_api_base_url_strips_trailing_slash PASSED [ 42%]
+tests/tests_for_models.py::test_issue_extra_fields_ignored PASSED        [ 43%]
+tests/tests_for_models.py::test_merge_request_basic PASSED               [ 44%]
+tests/tests_for_models.py::test_config_env_loading PASSED                [ 46%]
+tests/tests_for_oauth_cli.py::test_missing_client_id_errors PASSED       [ 47%]
+tests/tests_for_oauth_cli.py::test_success_prints_only_token PASSED      [ 48%]
+tests/tests_for_oauth_cli.py::test_reads_config_from_env PASSED          [ 49%]
+tests/tests_for_oauth_cli.py::test_bad_redirect_port_errors PASSED       [ 50%]
+tests/tests_for_oauth_cli.py::test_oauth_error_returns_one PASSED        [ 51%]
+tests/tests_for_oauth_service.py::test_make_pkce_challenge_is_s256_of_verifier PASSED [ 52%]
+tests/tests_for_oauth_service.py::test_cache_path_is_per_host_and_private PASSED [ 53%]
+tests/tests_for_oauth_service.py::test_token_if_valid_expiry PASSED      [ 55%]
+tests/tests_for_oauth_service.py::test_store_token_response_roundtrip PASSED [ 56%]
+tests/tests_for_oauth_service.py::test_store_token_response_requires_access_token PASSED [ 57%]
+tests/tests_for_oauth_service.py::test_refresh_access_token_success PASSED [ 58%]
+tests/tests_for_oauth_service.py::test_refresh_access_token_returns_none_on_error PASSED [ 59%]
+tests/tests_for_oauth_service.py::test_get_access_token_reuses_valid_cache PASSED [ 60%]
+tests/tests_for_oauth_service.py::test_get_access_token_refreshes_expired_cache PASSED [ 61%]
+tests/tests_for_oauth_service.py::test_get_access_token_requires_client_id PASSED [ 62%]
+tests/tests_for_packages_service.py::test_upload_generic_package_url_shape PASSED [ 64%]
+tests/tests_for_packages_service.py::test_download_generic_package PASSED [ 65%]
+tests/tests_for_packages_service.py::test_list_packages PASSED           [ 66%]
+tests/tests_for_repo_files_service.py::test_get_file_url_encoded PASSED  [ 67%]
+tests/tests_for_repo_files_service.py::test_download_file_writes_to_dest PASSED [ 68%]
+tests/tests_for_repo_files_service.py::test_download_directory_walks_tree PASSED [ 69%]
+tests/tests_for_sync_cli.py::test_missing_repo_errors PASSED             [ 70%]
+tests/tests_for_sync_cli.py::test_missing_client_id_errors PASSED        [ 71%]
+tests/tests_for_sync_cli.py::test_success_prints_path_and_forwards_args PASSED [ 73%]
+tests/tests_for_sync_cli.py::test_reads_config_from_env PASSED           [ 74%]
+tests/tests_for_sync_cli.py::test_oauth_error_returns_one PASSED         [ 75%]
+tests/tests_for_sync_cli.py::test_sync_error_returns_one PASSED          [ 76%]
+tests/tests_for_sync_cli.py::test_bad_redirect_port_errors PASSED        [ 77%]
+tests/tests_for_work_items_service.py::test_make_work_item_gid_passthrough_and_coerce PASSED [ 78%]
+tests/tests_for_work_items_service.py::test_work_item_from_node_flattens_widgets PASSED [ 79%]
+tests/tests_for_work_items_service.py::test_graphql_raises_on_errors PASSED [ 80%]
+tests/tests_for_work_items_service.py::test_paginate_graphql_follows_end_cursor PASSED [ 82%]
+tests/tests_for_work_items_service.py::test_get_work_item_by_global_id PASSED [ 83%]
+tests/tests_for_work_items_service.py::test_get_work_item_by_project_path_and_iid_uses_namespace_lookup PASSED [ 84%]
+tests/tests_for_work_items_service.py::test_get_work_item_missing_raises PASSED [ 85%]
+tests/tests_for_work_items_service.py::test_search_work_items_paginates_and_translates_state PASSED [ 86%]
+tests/tests_for_work_items_service.py::test_search_work_items_group_scope_uses_group_field PASSED [ 87%]
+tests/tests_for_work_items_service.py::test_search_work_items_requires_one_scope PASSED [ 88%]
+tests/tests_for_work_items_service.py::test_set_work_item_state_closes_via_workItemUpdate PASSED [ 89%]
+tests/tests_for_work_items_service.py::test_set_work_item_state_mutation_errors_raise PASSED [ 91%]
+tests/tests_for_work_items_service.py::test_list_work_item_notes_filters_system_notes PASSED [ 92%]
+tests/tests_for_work_items_service.py::test_comment_on_work_item_creates_note PASSED [ 93%]
+tests/tests_for_work_items_service.py::test_reply_to_work_item_discussion_threads_via_discussion_id PASSED [ 94%]
+tests/tests_for_work_items_service.py::test_set_work_item_labels_add_passes_addLabelIds PASSED [ 95%]
+tests/tests_for_work_items_service.py::test_set_work_item_labels_remove_passes_removeLabelIds PASSED [ 96%]
+tests/tests_for_work_items_service.py::test_list_labels_for_project_includes_ancestor_groups PASSED [ 97%]
 tests/tests_for_work_items_service.py::test_create_label_passes_project_path_color_and_description PASSED [ 98%]
 tests/tests_for_work_items_service.py::test_create_label_group_scope_passes_group_path PASSED [100%]
 
-============================== 63 passed in 1.91s ==============================
+============================== 89 passed in 1.80s ==============================

pjdev_gitlab-5.1.12/tests/tests_for_git_sync_service.py

@@ -0,0 +1,322 @@
+from pathlib import Path
+
+import pytest
+
+from pjdev_gitlab import git_sync_service as gss
+from pjdev_gitlab.git_sync_service import SyncError, build_remote_url, default_target_dir
+
+
+class FakeGit:
+    """Records git invocations and answers the read-only queries ``sync_repo``
+    makes, so the update path can be exercised without real git or network.
+
+    Knobs model repo state: which branch is checked out, whether ``origin``
+    exists, and which branches exist locally.
+    """
+
+    def __init__(self, *, current_branch="main", has_origin=True, local_branches=("main",)):
+        self.calls = []
+        self.current_branch = current_branch
+        self.has_origin = has_origin
+        self.local_branches = set(local_branches)
+
+    def __call__(self, args, *, cwd=None, env=None):
+        args = list(args)
+        self.calls.append({"args": args, "cwd": cwd, "env": env})
+        if args and args[0] == "clone":
+            target = Path(args[-1])  # clone's final arg is the destination
+            (target / ".git").mkdir(parents=True, exist_ok=True)
+        elif args[:2] == ["symbolic-ref", "--short"]:
+            return self.current_branch
+        elif args[:2] == ["remote", "get-url"]:
+            if not self.has_origin:
+                raise SyncError("error: No such remote 'origin'")
+        elif args[:3] == ["rev-parse", "--verify", "--quiet"]:
+            branch = args[-1].rsplit("/", 1)[-1]  # refs/heads/<branch>
+            if branch not in self.local_branches:
+                raise SyncError("not a valid ref")
+        return ""
+
+
+# --------------------------------------------------------------------------- #
+# pure helpers
+# --------------------------------------------------------------------------- #
+@pytest.mark.parametrize(
+    "url,repo,expected",
+    [
+        ("https://gitlab.example.com", "g/s/n", "https://gitlab.example.com/g/s/n.git"),
+        ("https://gitlab.example.com/", "/g/n/", "https://gitlab.example.com/g/n.git"),
+        ("https://gitlab.example.com", "g/n.git", "https://gitlab.example.com/g/n.git"),
+    ],
+)
+def test_build_remote_url(url, repo, expected):
+    assert build_remote_url(url, repo) == expected
+
+
+def test_build_remote_url_empty_repo_errors():
+    with pytest.raises(SyncError):
+        build_remote_url("https://gitlab.example.com", "   ")
+
+
+@pytest.mark.parametrize(
+    "repo,expected",
+    [
+        ("developers/claude-skills", "claude-skills"),
+        ("g/s/name.git", "name"),
+        ("solo", "solo"),
+    ],
+)
+def test_default_target_dir(repo, expected):
+    assert default_target_dir(repo) == Path(expected)
+
+
+# --------------------------------------------------------------------------- #
+# sync_repo -- clone
+# --------------------------------------------------------------------------- #
+def test_clone_when_target_missing(tmp_path):
+    git = FakeGit()
+    target = tmp_path / "sub" / "claude-skills"
+    result = gss.sync_repo(
+        gitlab_url="https://gitlab.example.com",
+        repo_path="developers/claude-skills",
+        token="TOK",
+        target_dir=target,
+        runner=git,
+        on_status=lambda _m: None,
+    )
+
+    assert result.action == "cloned"
+    assert result.path == target.absolute()
+    assert result.remote_url == "https://gitlab.example.com/developers/claude-skills.git"
+
+    clone = next(c for c in git.calls if c["args"][0] == "clone")
+    # Username is embedded; the raw token never appears on the command line.
+    assert "https://oauth2@gitlab.example.com/developers/claude-skills.git" in clone["args"]
+    assert not any("TOK" in a for a in clone["args"])
+
+    # origin is reset to the plain, username-less, tokenless URL -- but only
+    # after confirming the remote exists, and addressed via cwd (not `-C`).
+    assert git.calls[-2]["args"] == ["remote", "get-url", "origin"]
+    set_url = git.calls[-1]
+    assert set_url["args"] == ["remote", "set-url", "origin", result.remote_url]
+    assert set_url["cwd"] == target.absolute()
+
+
+def test_clone_passes_token_via_askpass_env_only(tmp_path):
+    git = FakeGit()
+    gss.sync_repo(
+        gitlab_url="https://gitlab.example.com",
+        repo_path="g/n",
+        token="SECRET",
+        target_dir=tmp_path / "n",
+        runner=git,
+        on_status=lambda _m: None,
+    )
+    clone = next(c for c in git.calls if c["args"][0] == "clone")
+    env = clone["env"]
+    assert env["GIT_ASKPASS"]
+    assert env["GIT_TERMINAL_PROMPT"] == "0"
+    assert env[gss._TOKEN_ENV] == "SECRET"
+    # The askpass helper is cleaned up after the run.
+    assert not Path(env["GIT_ASKPASS"]).exists()
+
+
+def test_clone_with_branch(tmp_path):
+    git = FakeGit()
+    gss.sync_repo(
+        gitlab_url="https://gitlab.example.com",
+        repo_path="g/n",
+        token="TOK",
+        target_dir=tmp_path / "n",
+        branch="develop",
+        runner=git,
+        on_status=lambda _m: None,
+    )
+    clone = next(c for c in git.calls if c["args"][0] == "clone")
+    assert clone["args"][:3] == ["clone", "--branch", "develop"]
+
+
+# --------------------------------------------------------------------------- #
+# sync_repo -- update
+# --------------------------------------------------------------------------- #
+def test_update_when_target_is_repo(tmp_path):
+    target = tmp_path / "existing"
+    (target / ".git").mkdir(parents=True)
+    git = FakeGit()
+
+    result = gss.sync_repo(
+        gitlab_url="https://gitlab.example.com",
+        repo_path="g/n",
+        token="TOK",
+        target_dir=target,
+        runner=git,
+        on_status=lambda _m: None,
+    )
+
+    assert result.action == "updated"
+    args = [c["args"] for c in git.calls]
+    assert not any(a[0] == "clone" for a in args)
+    # With no --branch, sync the branch actually checked out (here "main"),
+    # fetched by name so FETCH_HEAD is that branch and not the remote default.
+    assert ["symbolic-ref", "--short", "HEAD"] in args
+    fetch = next(c for c in git.calls if c["args"][0] == "fetch")
+    assert fetch["args"] == ["fetch", "https://oauth2@gitlab.example.com/g/n.git", "main"]
+    assert fetch["cwd"] == target.absolute()
+    assert ["checkout", "main"] in args
+    assert ["merge", "--ff-only", "FETCH_HEAD"] in args
+
+
+def test_update_with_existing_branch_checks_out_and_ff(tmp_path):
+    target = tmp_path / "existing"
+    (target / ".git").mkdir(parents=True)
+    git = FakeGit(local_branches=("main", "release"))
+
+    gss.sync_repo(
+        gitlab_url="https://gitlab.example.com",
+        repo_path="g/n",
+        token="TOK",
+        target_dir=target,
+        branch="release",
+        runner=git,
+        on_status=lambda _m: None,
+    )
+    args = [c["args"] for c in git.calls]
+    assert ["fetch", "https://oauth2@gitlab.example.com/g/n.git", "release"] in args
+    assert ["checkout", "release"] in args
+    assert ["merge", "--ff-only", "FETCH_HEAD"] in args
+    # An existing branch is checked out, never recreated.
+    assert not any(a[:2] == ["checkout", "-b"] for a in args)
+
+
+def test_update_with_new_branch_creates_from_fetch_head(tmp_path):
+    target = tmp_path / "existing"
+    (target / ".git").mkdir(parents=True)
+    git = FakeGit(current_branch="main", local_branches=("main",))  # "release" absent
+
+    gss.sync_repo(
+        gitlab_url="https://gitlab.example.com",
+        repo_path="g/n",
+        token="TOK",
+        target_dir=target,
+        branch="release",
+        runner=git,
+        on_status=lambda _m: None,
+    )
+    args = [c["args"] for c in git.calls]
+    assert ["fetch", "https://oauth2@gitlab.example.com/g/n.git", "release"] in args
+    # Branch is new to this checkout: create it at the fetched tip, no ff-merge.
+    assert ["checkout", "-b", "release", "FETCH_HEAD"] in args
+    assert not any(a[:2] == ["merge", "--ff-only"] for a in args)
+
+
+def test_update_adds_origin_when_absent(tmp_path):
+    target = tmp_path / "existing"
+    (target / ".git").mkdir(parents=True)
+    git = FakeGit(has_origin=False)
+
+    result = gss.sync_repo(
+        gitlab_url="https://gitlab.example.com",
+        repo_path="g/n",
+        token="TOK",
+        target_dir=target,
+        runner=git,
+        on_status=lambda _m: None,
+    )
+    args = [c["args"] for c in git.calls]
+    # A checkout without an `origin` gets one added rather than failing set-url.
+    assert ["remote", "add", "origin", result.remote_url] in args
+    assert not any(a[:2] == ["remote", "set-url"] for a in args)
+
+
+def test_update_detached_head_errors(tmp_path):
+    target = tmp_path / "existing"
+    (target / ".git").mkdir(parents=True)
+    git = FakeGit(current_branch="")  # symbolic-ref yields nothing -> detached
+
+    with pytest.raises(SyncError, match="detached HEAD"):
+        gss.sync_repo(
+            gitlab_url="https://gitlab.example.com",
+            repo_path="g/n",
+            token="TOK",
+            target_dir=target,
+            runner=git,
+            on_status=lambda _m: None,
+        )
+    # It never fetched or merged after failing to resolve the branch.
+    assert not any(c["args"][0] in ("fetch", "merge") for c in git.calls)
+
+
+def test_clone_failure_removes_partial_target(tmp_path):
+    target = tmp_path / "n"
+
+    def failing_clone(args, *, cwd=None, env=None):
+        args = list(args)
+        if args[0] == "clone":
+            # git often creates the target dir before failing on auth/network.
+            Path(args[-1]).mkdir(parents=True, exist_ok=True)
+            raise SyncError("`git clone ...` failed (128): auth")
+        return ""
+
+    with pytest.raises(SyncError, match="auth"):
+        gss.sync_repo(
+            gitlab_url="https://gitlab.example.com",
+            repo_path="g/n",
+            token="TOK",
+            target_dir=target,
+            runner=failing_clone,
+            on_status=lambda _m: None,
+        )
+    # The partial checkout is cleaned up so a re-run starts fresh.
+    assert not target.exists()
+
+
+def test_target_exists_but_not_a_repo_errors(tmp_path):
+    target = tmp_path / "plainfile"
+    target.mkdir()
+    (target / "some.txt").write_text("hi")  # a dir, but no .git
+    git = FakeGit()
+
+    with pytest.raises(SyncError, match="not a git repository"):
+        gss.sync_repo(
+            gitlab_url="https://gitlab.example.com",
+            repo_path="g/n",
+            token="TOK",
+            target_dir=target,
+            runner=git,
+            on_status=lambda _m: None,
+        )
+    assert git.calls == []
+
+
+def test_missing_token_errors(tmp_path):
+    with pytest.raises(SyncError, match="token is required"):
+        gss.sync_repo(
+            gitlab_url="https://gitlab.example.com",
+            repo_path="g/n",
+            token="",
+            target_dir=tmp_path / "n",
+            runner=FakeGit(),
+        )
+
+
+def test_ff_only_failure_propagates(tmp_path):
+    target = tmp_path / "existing"
+    (target / ".git").mkdir(parents=True)
+
+    def failing_git(args, *, cwd=None, env=None):
+        args = list(args)
+        if args[:2] == ["symbolic-ref", "--short"]:
+            return "main"
+        if args[:2] == ["merge", "--ff-only"]:
+            raise SyncError("`git merge --ff-only FETCH_HEAD` failed (128): diverged")
+        return ""
+
+    with pytest.raises(SyncError, match="diverged"):
+        gss.sync_repo(
+            gitlab_url="https://gitlab.example.com",
+            repo_path="g/n",
+            token="TOK",
+            target_dir=target,
+            runner=failing_git,
+            on_status=lambda _m: None,
+        )

pjdev_gitlab-5.1.12/tests/tests_for_sync_cli.py

@@ -0,0 +1,127 @@
+import sys
+from pathlib import Path
+
+import pytest
+
+from pjdev_gitlab import sync_cli
+from pjdev_gitlab.git_sync_service import SyncError, SyncResult
+from pjdev_gitlab.oauth_service import OAuthError
+
+
+@pytest.fixture(autouse=True)
+def _clear_env(monkeypatch):
+    for key in (
+        "GL_REPO",
+        "GL_SYNC_TARGET",
+        "GL_SYNC_BRANCH",
+        "GL_GITLAB_URL",
+        "GL_OAUTH_CLIENT_ID",
+        "GL_OAUTH_CLIENT_SECRET",
+        "GL_OAUTH_REDIRECT_PORT",
+        "GL_OAUTH_SCOPES",
+    ):
+        monkeypatch.delenv(key, raising=False)
+
+
+def _run(monkeypatch, argv):
+    monkeypatch.setattr(sys, "argv", ["pjdev-gitlab-sync", *argv])
+    return sync_cli.main()
+
+
+def _stub_token(monkeypatch, token="TOK"):
+    monkeypatch.setattr(sync_cli, "get_access_token", lambda **_k: token)
+
+
+def test_missing_repo_errors(monkeypatch, capsys):
+    _stub_token(monkeypatch)
+    rc = _run(monkeypatch, ["--client-id", "cid"])
+    assert rc == 2
+    assert "repo" in capsys.readouterr().err.lower()
+
+
+def test_missing_client_id_errors(monkeypatch, capsys):
+    rc = _run(monkeypatch, ["g/n"])
+    assert rc == 2
+    assert "client id" in capsys.readouterr().err.lower()
+
+
+def test_success_prints_path_and_forwards_args(monkeypatch, capsys):
+    _stub_token(monkeypatch, "TOK123")
+    captured = {}
+
+    def fake_sync(**kwargs):
+        captured.update(kwargs)
+        return SyncResult(action="cloned", path=Path("/abs/claude-skills"), remote_url="url")
+
+    monkeypatch.setattr(sync_cli, "sync_repo", fake_sync)
+    rc = _run(
+        monkeypatch,
+        [
+            "developers/claude-skills",
+            "--gitlab-url",
+            "https://gitlab.example.com",
+            "--client-id",
+            "cid",
+            "--target",
+            "/abs/claude-skills",
+            "--branch",
+            "main",
+        ],
+    )
+    assert rc == 0
+    assert capsys.readouterr().out.strip() == "/abs/claude-skills"
+    assert captured["gitlab_url"] == "https://gitlab.example.com"
+    assert captured["repo_path"] == "developers/claude-skills"
+    assert captured["token"] == "TOK123"
+    assert captured["target_dir"] == "/abs/claude-skills"
+    assert captured["branch"] == "main"
+
+
+def test_reads_config_from_env(monkeypatch, capsys):
+    monkeypatch.setenv("GL_REPO", "g/env-repo")
+    monkeypatch.setenv("GL_GITLAB_URL", "https://env.example.com")
+    monkeypatch.setenv("GL_OAUTH_CLIENT_ID", "env-cid")
+    _stub_token(monkeypatch)
+    captured = {}
+    monkeypatch.setattr(
+        sync_cli,
+        "sync_repo",
+        lambda **k: captured.update(k)
+        or SyncResult(action="updated", path=Path("/x"), remote_url="u"),
+    )
+    rc = _run(monkeypatch, [])
+    assert rc == 0
+    assert captured["repo_path"] == "g/env-repo"
+    assert captured["gitlab_url"] == "https://env.example.com"
+
+
+def test_oauth_error_returns_one(monkeypatch, capsys):
+    def boom(**_k):
+        raise OAuthError("auth nope")
+
+    monkeypatch.setattr(sync_cli, "get_access_token", boom)
+    rc = _run(monkeypatch, ["g/n", "--client-id", "cid"])
+    assert rc == 1
+    out = capsys.readouterr()
+    assert out.out == ""
+    assert "auth nope" in out.err
+
+
+def test_sync_error_returns_one(monkeypatch, capsys):
+    _stub_token(monkeypatch)
+
+    def boom(**_k):
+        raise SyncError("clone nope")
+
+    monkeypatch.setattr(sync_cli, "sync_repo", boom)
+    rc = _run(monkeypatch, ["g/n", "--client-id", "cid"])
+    assert rc == 1
+    out = capsys.readouterr()
+    assert out.out == ""
+    assert "clone nope" in out.err
+
+
+def test_bad_redirect_port_errors(monkeypatch):
+    with pytest.raises(SystemExit) as exc:
+        _run(monkeypatch, ["g/n", "--client-id", "cid", "--redirect-port", "notaport"])
+    assert exc.value.code == 2