pygitcode 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

gitcode_cli/__init__.py

@@ -1,3 +1,3 @@
 __all__ = ["__version__"]
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"

gitcode_cli/adapters/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from .base import AdapterActionResult
+from .issues import IssueAdapter
+from .pulls import PullRequestAdapter
+
+__all__ = ["AdapterActionResult", "IssueAdapter", "PullRequestAdapter"]

gitcode_cli/adapters/base.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class AdapterActionResult:
+    item: dict[str, Any] | None = None
+    items: list[dict[str, Any]] | None = None
+    message: str | None = None
+    warning: str | None = None
+    degraded: bool = False
+    approximated: bool = False

gitcode_cli/adapters/capabilities.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import click
+
+CAPABILITY_MESSAGES = {
+    "ISSUE_COMMENT_LAST_NOT_FOUND": "No editable issue comment from the current user was found.",
+    "ISSUE_COMMENT_OWNERSHIP_UNVERIFIABLE": (
+        "Unable to verify the current user's issue comments on GitCode; refusing to edit or delete comments safely."
+    ),
+    "ISSUE_CREATE_IF_NONE_REQUIRES_EDIT_LAST": "--create-if-none can only be used together with --edit-last.",
+    "ISSUE_DELETE": "GitCode API does not support deleting issues.",
+    "ISSUE_DEVELOP_BASE": "--base and --name are not supported by 'gc issue develop'",
+    "ISSUE_DEVELOP_NAME": "--base and --name are not supported by 'gc issue develop'",
+    "ISSUE_STATUS_GH_SEMANTICS": "GitCode-limited approximation of gh issue status",
+    "PR_MERGE_AUTHOR_EMAIL": "GitCode merge API does not support --author-email.",
+    "PR_MERGE_AUTO": "GitCode merge API does not support --auto.",
+    "PR_REVIEW_REQUEST_CHANGES": (
+        "GitCode review API does not support request-changes reviews; the pull request comment was posted instead."
+    ),
+    "PR_STATUS_GH_SEMANTICS": ("GitCode API approximation -- user-specific filtering is not available"),
+}
+
+
+def capability_message(feature: str) -> str:
+    return CAPABILITY_MESSAGES[feature]
+
+
+def unsupported(feature: str) -> click.ClickException:
+    return click.ClickException(capability_message(feature))

gitcode_cli/adapters/issues.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from ..errors import APIError
+from ..services import IssueService, UserService
+from .base import AdapterActionResult
+from .capabilities import capability_message, unsupported
+
+
+def _normalize_multi_values(values: tuple[str, ...] | None) -> str | None:
+    if not values:
+        return None
+    return ",".join(values)
+
+
+def _extract_label_names(issue: dict[str, Any] | None) -> list[str]:
+    labels = issue.get("labels") if isinstance(issue, dict) else None
+    if not labels:
+        return []
+    if isinstance(labels, str):
+        return [part.strip() for part in labels.split(",") if part.strip()]
+
+    names: list[str] = []
+    if isinstance(labels, list):
+        for label in labels:
+            if isinstance(label, dict):
+                name = label.get("name") or label.get("title")
+                if name:
+                    names.append(str(name))
+            elif label:
+                names.append(str(label))
+    return names
+
+
+def _extract_login(data: dict[str, Any] | None) -> str | None:
+    if not isinstance(data, dict):
+        return None
+    for key in ("login", "username", "name"):
+        value = data.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    user = data.get("user")
+    if isinstance(user, dict):
+        return _extract_login(user)
+    author = data.get("author")
+    if isinstance(author, dict):
+        return _extract_login(author)
+    return None
+
+
+class IssueAdapter:
+    def __init__(self, service: IssueService, user_service: UserService | None = None):
+        self.service = service
+        self.user_service = user_service
+
+    def list_issues(
+        self,
+        owner: str,
+        repo: str,
+        *,
+        state: str | None,
+        labels: tuple[str, ...] | None,
+        author: str | None,
+        assignee: str | None,
+        milestone: str | None,
+        mention: str | None,
+        search: str | None,
+        limit: int | None,
+    ) -> Any:
+        items = self.service.list(
+            owner,
+            repo,
+            state=state,
+            labels=_normalize_multi_values(labels),
+            creator=author,
+            assignee=assignee,
+            milestone=milestone,
+            mention=mention,
+            search=search,
+        )
+        if limit is not None:
+            return items[:limit]
+        return items
+
+    def create_issue(
+        self,
+        owner: str,
+        repo: str,
+        *,
+        title: str,
+        body: str | None,
+        assignee: str | None,
+        labels: tuple[str, ...] | None,
+        milestone: str | None,
+    ) -> dict[str, Any] | None:
+        return self.service.create(
+            owner,
+            repo,
+            title=title,
+            body=body,
+            assignee=assignee,
+            labels=_normalize_multi_values(labels),
+            milestone=milestone,
+        )
+
+    def close_issue(
+        self,
+        owner: str,
+        repo: str,
+        number: str,
+        *,
+        comment: str | None,
+        reason: str | None,
+    ) -> AdapterActionResult:
+        current = self.service.get(owner, repo, number)
+        if current and current.get("state") == "closed":
+            if comment:
+                self.service.comment(owner, repo, number, comment)
+                return AdapterActionResult(item=current, message="already_closed_commented")
+            return AdapterActionResult(item=current, message="already_closed")
+        if comment:
+            self.service.comment(owner, repo, number, comment)
+        payload: dict[str, Any] = {"state": "close"}
+        if reason:
+            payload["state_reason"] = reason
+        item = self.service.update(owner, repo, number, **payload)
+        return AdapterActionResult(item=item, message="closed")
+
+    def comment_issue(self, owner: str, repo: str, number: str, *, body: str) -> dict[str, Any] | None:
+        return self.service.comment(owner, repo, number, body)
+
+    def manage_comment_history(
+        self,
+        owner: str,
+        repo: str,
+        number: str,
+        *,
+        body: str | None,
+        delete_last: bool,
+        create_if_none: bool,
+    ) -> AdapterActionResult:
+        comment = self._find_last_owned_comment(owner, repo, number)
+        if delete_last:
+            if comment is None:
+                raise click.ClickException(capability_message("ISSUE_COMMENT_LAST_NOT_FOUND"))
+            self.service.delete_comment(owner, repo, comment["id"])
+            return AdapterActionResult(item=comment, message="deleted")
+        if comment is None:
+            if create_if_none:
+                item = self.service.comment(owner, repo, number, body or "")
+                return AdapterActionResult(item=item, message="created")
+            raise click.ClickException(capability_message("ISSUE_COMMENT_LAST_NOT_FOUND"))
+        item = self.service.update_comment(owner, repo, comment["id"], body or "")
+        return AdapterActionResult(item=item, message="edited")
+
+    def _find_last_owned_comment(self, owner: str, repo: str, number: str) -> dict[str, Any] | None:
+        if self.user_service is None:
+            raise click.ClickException(capability_message("ISSUE_COMMENT_OWNERSHIP_UNVERIFIABLE"))
+        try:
+            current_user = self.user_service.current()
+        except APIError as exc:
+            raise click.ClickException(capability_message("ISSUE_COMMENT_OWNERSHIP_UNVERIFIABLE")) from exc
+        current_login = _extract_login(current_user)
+        if not current_login:
+            raise click.ClickException(capability_message("ISSUE_COMMENT_OWNERSHIP_UNVERIFIABLE"))
+        comments = self.service.list_comments(owner, repo, number) or []
+        for comment in reversed(comments):
+            if not isinstance(comment, dict):
+                continue
+            if _extract_login(comment) == current_login:
+                return comment
+        return None
+
+    def reopen_issue(self, owner: str, repo: str, number: str) -> AdapterActionResult:
+        current = self.service.get(owner, repo, number)
+        if current and current.get("state") == "open":
+            return AdapterActionResult(item=current, message="already_open")
+        item = self.service.update(owner, repo, number, state="reopen")
+        return AdapterActionResult(item=item, message="reopened")
+
+    def delete_issue(self, owner: str, repo: str, number: str) -> AdapterActionResult:  # noqa: ARG002
+        raise unsupported("ISSUE_DELETE")
+
+    def edit_issue(
+        self,
+        owner: str,
+        repo: str,
+        number: str,
+        *,
+        title: str | None,
+        body: str | None,
+        add_assignee: str | None,
+        add_labels: tuple[str, ...] | None,
+        milestone: str | None,
+        remove_milestone: bool,
+    ) -> dict[str, Any] | None:
+        data = {k: v for k, v in {"title": title, "body": body}.items() if v is not None}
+
+        if add_assignee is not None:
+            data["assignee"] = add_assignee
+
+        if add_labels:
+            current = self.service.get(owner, repo, number)
+            existing = _extract_label_names(current)
+            merged: list[str] = []
+            seen: set[str] = set()
+            for label in [*existing, *list(add_labels)]:
+                normalized = label.strip()
+                if normalized and normalized not in seen:
+                    seen.add(normalized)
+                    merged.append(normalized)
+            data["labels"] = ",".join(merged)
+
+        if milestone is not None:
+            data["milestone"] = milestone
+        if remove_milestone:
+            data["milestone"] = ""
+        return self.service.update(owner, repo, number, **data)
+
+    def status(self, owner: str, repo: str) -> AdapterActionResult:
+        items = self.service.list(owner, repo, state="open")
+        return AdapterActionResult(
+            items=items,
+            message=capability_message("ISSUE_STATUS_GH_SEMANTICS"),
+            approximated=True,
+        )
+
+    def develop(self, owner: str, repo: str, number: str, *, base: str | None, name: str | None) -> AdapterActionResult:  # noqa: ARG002
+        if base is not None:
+            raise unsupported("ISSUE_DEVELOP_BASE")
+        if name is not None:
+            raise unsupported("ISSUE_DEVELOP_NAME")
+        return AdapterActionResult(
+            message=f"Opening issue #{number} in the browser instead.",
+            warning="Note: 'issue develop' does not create a local branch on GitCode.",
+        )

gitcode_cli/adapters/pulls.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..services import PullRequestService
+from .base import AdapterActionResult
+from .capabilities import capability_message
+
+
+def _normalize_multi_values(values: tuple[str, ...] | None) -> str | None:
+    if not values:
+        return None
+    return ",".join(values)
+
+
+class PullRequestAdapter:
+    def __init__(self, service: PullRequestService):
+        self.service = service
+
+    def list_prs(
+        self,
+        owner: str,
+        repo: str,
+        *,
+        state: str | None,
+        author: str | None,
+        base: str | None,
+        assignee: str | None,
+        draft: bool | None,
+        head: str | None,
+        labels: tuple[str, ...] | None,
+        search: str | None,
+        limit: int | None,
+    ) -> Any:
+        items = self.service.list(
+            owner,
+            repo,
+            state=state,
+            author=author,
+            base=base,
+            assignee=assignee,
+            draft=draft,
+            head=head,
+            labels=_normalize_multi_values(labels),
+            search=search,
+        )
+        if limit is not None:
+            return items[:limit]
+        return items
+
+    def create_pr(
+        self,
+        owner: str,
+        repo: str,
+        *,
+        title: str,
+        body: str | None,
+        base: str,
+        head: str,
+        draft: bool,
+        milestone: str | None,
+        labels: tuple[str, ...] | None,
+        reviewers: tuple[str, ...] | None,
+        assignees: tuple[str, ...] | None,
+        dry_run: bool,
+    ) -> AdapterActionResult:
+        payload = {
+            "title": title,
+            "body": body,
+            "base": base,
+            "head": head,
+            "draft": draft,
+            "labels": _normalize_multi_values(labels),
+            "assignees": _normalize_multi_values(assignees),
+            "reviewers": _normalize_multi_values(reviewers),
+            "milestone": milestone,
+        }
+        if dry_run:
+            return AdapterActionResult(item={k: v for k, v in payload.items() if v is not None})
+        return AdapterActionResult(item=self.service.create(owner, repo, **payload))
+
+    def merge_pr(
+        self,
+        owner: str,
+        repo: str,
+        number: int,
+        *,
+        merge_method: str,
+        body: str | None,
+        subject: str | None,
+        admin: bool,
+    ) -> dict[str, Any] | None:
+        payload = {
+            "merge_method": merge_method,
+            "description": body,
+            "title": subject,
+            "force_merge": True if admin else None,
+        }
+        return self.service.merge(owner, repo, number, **payload)
+
+    def review_pr(
+        self,
+        owner: str,
+        repo: str,
+        number: int,
+        *,
+        approve: bool,  # noqa: ARG002
+        body: str | None,
+        comment: bool,
+        request_changes: bool,
+        force: bool,
+    ) -> AdapterActionResult:
+        if comment:
+            item = self.service.comment(owner, repo, number, body=body or "")
+            return AdapterActionResult(item=item)
+        if request_changes:
+            item = self.service.comment(owner, repo, number, body=body or "")
+            return AdapterActionResult(
+                item=item,
+                message=capability_message("PR_REVIEW_REQUEST_CHANGES"),
+                degraded=True,
+            )
+        item = self.service.review(owner, repo, number, force=force)
+        return AdapterActionResult(item=item)
+
+    def edit_pr(
+        self,
+        owner: str,
+        repo: str,
+        number: int,
+        *,
+        title: str | None,
+        body: str | None,
+        base: str | None,
+        add_assignee: str | None,
+        add_label: str | None,
+        add_reviewer: str | None,
+        remove_assignee: str | None,
+        remove_label: str | None,
+        remove_reviewer: str | None,
+        milestone: str | None,
+        remove_milestone: bool,
+    ) -> dict[str, Any] | None:
+        data = {
+            k: v
+            for k, v in {
+                "title": title,
+                "body": body,
+                "base": base,
+                "assignee": add_assignee,
+                "labels": add_label,
+                "reviewer": add_reviewer,
+                "unassignee": remove_assignee,
+                "unset_labels": remove_label,
+                "unset_reviewer": remove_reviewer,
+                "milestone": milestone,
+            }.items()
+            if v is not None
+        }
+        if remove_milestone:
+            data["milestone"] = ""
+        return self.service.update(owner, repo, number, **data)
+
+    def status(self, owner: str, repo: str) -> AdapterActionResult:
+        items = self.service.list(owner, repo, state="open")
+        return AdapterActionResult(
+            items=items,
+            message=capability_message("PR_STATUS_GH_SEMANTICS"),
+            approximated=True,
+        )

gitcode_cli/cli.py

@@ -1,6 +1,11 @@
 from __future__ import annotations
 
+import contextlib
+import importlib.metadata
+import sys
+
 import click
+from click.shell_completion import get_completion_class
 
 from . import __version__
 from .commands.auth import auth_group
@@ -9,14 +14,46 @@ from .commands.pr import pr_group
 from .config import get_token
 from .context import AppContext
 from .errors import GCError
+from .helptext import GCSectionGroup, set_gc_help
+from .utils import safe_echo
+
+
+def _configure_stdout_encoding() -> None:
+    if sys.platform != "win32":
+        return
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure") and stream.isatty():
+            with contextlib.suppress(Exception):
+                stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[attr-defined]
+
+
+def _get_version() -> str:
+    try:
+        return importlib.metadata.version("pygitcode")
+    except importlib.metadata.PackageNotFoundError:
+        return __version__
 
 
-@click.group(context_settings={"help_option_names": ["-h", "--help"]})
-@click.version_option(version=__version__, prog_name="gc")
+class _GCMainGroup(GCSectionGroup):
+    def invoke(self, ctx: click.Context):
+        try:
+            return super().invoke(ctx)
+        except GCError as exc:
+            safe_echo(f"error: {exc}", err=True)
+            ctx.exit(1)
+
+
+@click.group(
+    cls=_GCMainGroup,
+    context_settings={"help_option_names": ["-h", "--help"]},
+    help="Work seamlessly with GitCode from the command line.",
+)
+@click.version_option(version=_get_version(), prog_name="gitcode")
 @click.option("--repo", "repo_name", "-R", help="Select another repository using the [HOST/]OWNER/REPO format.")
 @click.option("--token", hidden=True, help="Override authentication token.")
 @click.pass_context
 def main(ctx: click.Context, repo_name: str | None, token: str | None) -> None:
+    _configure_stdout_encoding()
     ctx.ensure_object(dict)
     try:
         resolved_token = token or get_token()
@@ -25,14 +62,42 @@ def main(ctx: click.Context, repo_name: str | None, token: str | None) -> None:
     ctx.obj["app"] = AppContext(token=resolved_token or "", repo=repo_name)
 
 
-@main.result_callback()
-def process_result(*_args: object, **_kwargs: object) -> None:
-    return None
+set_gc_help(
+    main,
+    gc_usage="gc <command> <subcommand> [flags]",
+    gc_command_sections=[
+        ("CORE COMMANDS", ["auth", "issue", "pr"]),
+        ("ADDITIONAL COMMANDS", ["completion", "version"]),
+    ],
+    gc_examples=[
+        "gc issue create",
+        "gc pr list -R owner/repo",
+        "gc auth login",
+    ],
+    gc_learn_more=[
+        "Use `gc <command> <subcommand> --help` for more information about a command.",
+    ],
+)
+
 
+auth_group.short_help = "Authenticate gc with GitCode"
+issue_group.short_help = "Manage issues"
+pr_group.short_help = "Manage pull requests"
 
-@main.command("version")
+
+@main.command("version", short_help="Show gc version", help="Show gc version.")
 def version_command() -> None:
-    click.echo(f"gc version {__version__}")
+    safe_echo(f"gitcode version {_get_version()}")
+
+
+@main.command("completion", short_help="Generate shell completion scripts", help="Generate shell completion scripts.")
+@click.argument("shell", type=click.Choice(["bash", "zsh", "fish"]))
+def completion_command(shell: str) -> None:
+    comp_class = get_completion_class(shell)
+    if comp_class is None:
+        raise click.ClickException(f"Shell completion not supported for: {shell}")
+    comp = comp_class(main, {}, "gc", "_GC_COMPLETE")
+    safe_echo(comp.source())
 
 
 main.add_command(auth_group)

gitcode_cli/cli_compat.py

@@ -10,6 +10,8 @@ from .utils import get_current_git_branch, get_default_git_branch, read_body_fil
 
 def get_body_from_options(body: str | None, body_file: str | None, editor: bool) -> str | None:
     """Resolve body text from inline text, file/stdin, or editor."""
+    if body is not None and body_file:
+        raise click.UsageError("--body and --body-file are mutually exclusive")
     if body is not None:
         return body
     if body_file:

gitcode_cli/client.py

@@ -5,7 +5,7 @@ from urllib.parse import urljoin
 
 import httpx
 
-from .errors import APIError
+from .errors import APIError, NetworkError
 
 BASE_URL = "https://api.gitcode.com/api/v5/"
 
@@ -29,13 +29,27 @@ class GitCodeClient:
         merged_params: dict[str, Any] = {"access_token": self.token}
         if params:
             merged_params.update({k: v for k, v in params.items() if v is not None})
-        response = self._client.request(
-            method,
-            urljoin(self.base_url, path.lstrip("/")),
-            params=merged_params,
-            json=json,
-            headers={"Accept": accept},
-        )
+        try:
+            response = self._client.request(
+                method,
+                urljoin(self.base_url, path.lstrip("/")),
+                params=merged_params,
+                json=json,
+                headers={"Accept": accept},
+            )
+        except httpx.TimeoutException as exc:
+            raise NetworkError(f"Request timed out: {exc}") from exc
+        except httpx.ConnectError as exc:
+            raise NetworkError(f"Connection failed: {exc}") from exc
+        except httpx.HTTPError as exc:
+            raise NetworkError(f"Network error: {exc}") from exc
+        if response.status_code == 401:
+            try:
+                data = response.json()
+                original = data.get("message") or str(data)
+            except Exception:
+                original = response.text
+            raise APIError(f"Authentication failed: {original}. Run 'gc auth login' to authenticate.", 401)
         if response.status_code >= 400:
             try:
                 data = response.json()

gitcode_cli/commands/auth.py

@@ -2,15 +2,17 @@ from __future__ import annotations
 
 import click
 
-from ..config import save_config
+from ..config import get_token, load_config, save_config
+from ..helptext import GCSectionGroup
+from ..utils import safe_echo
 
 
-@click.group("auth")
+@click.group("auth", cls=GCSectionGroup, help="Authenticate gc with GitCode.")
 def auth_group() -> None:
     pass
 
 
-@auth_group.command("login")
+@auth_group.command("login", short_help="Authenticate with a GitCode token", help="Authenticate with a GitCode token.")
 @click.option("--with-token", is_flag=True, help="Read token from stdin.")
 def auth_login(with_token: bool) -> None:
     if with_token:
@@ -20,4 +22,34 @@ def auth_login(with_token: bool) -> None:
     else:
         token = click.prompt("GitCode token", hide_input=True)
     save_config({"token": token})
-    click.echo("Authentication saved.")
+    safe_echo("Authentication saved.")
+
+
+@auth_group.command("logout", short_help="Remove saved authentication", help="Remove saved authentication.")
+def auth_logout() -> None:
+    config = load_config()
+    if "token" not in config:
+        raise click.ClickException("Not logged in.")
+    del config["token"]
+    save_config(config)
+    safe_echo("Logged out.")
+
+
+@auth_group.command("status", short_help="Show authentication status", help="Show authentication status.")
+def auth_status() -> None:
+    try:
+        token = get_token()
+    except Exception:
+        safe_echo("Not logged in. Run `gc auth login` to authenticate.")
+        return
+    masked = token[:4] + "****" if len(token) > 4 else "****"
+    safe_echo(f"Logged in to GitCode (token: {masked})")
+
+
+@auth_group.command("token", short_help="Print the active token", help="Print the active token.")
+def auth_token() -> None:
+    try:
+        token = get_token()
+    except Exception as exc:
+        raise click.ClickException(str(exc)) from exc
+    safe_echo(token)