git-alternative 0.2.2__py3-none-any.whl

git_alternative/__init__.py

@@ -0,0 +1,63 @@
+"""
+git-alternative: Python SDK for the Forge Git collaboration platform.
+
+Forge is a keyboard-driven, self-hosted Git forge with full REST API support.
+This package provides a clean Python interface for all Forge operations.
+"""
+
+from git_alternative.client import ForgeClient
+from git_alternative.exceptions import (
+    ForgeAuthError,
+    ForgeConflictError,
+    ForgeError,
+    ForgeNotFoundError,
+    ForgeValidationError,
+)
+from git_alternative.models import (
+    Branch,
+    CIConfig,
+    Comment,
+    CommitSummary,
+    CreateRepoRequest,
+    Issue,
+    IssueState,
+    Label,
+    MergeStrategy,
+    PaginatedResponse,
+    Pipeline,
+    PipelineState,
+    PipelineTrigger,
+    PrState,
+    PullRequest,
+    Repository,
+    SshKey,
+    User,
+)
+
+__version__ = "0.2.2"
+__all__ = [
+    "ForgeClient",
+    "ForgeError",
+    "ForgeAuthError",
+    "ForgeNotFoundError",
+    "ForgeConflictError",
+    "ForgeValidationError",
+    "Repository",
+    "CreateRepoRequest",
+    "Issue",
+    "IssueState",
+    "PullRequest",
+    "PrState",
+    "MergeStrategy",
+    "Pipeline",
+    "PipelineState",
+    "PipelineTrigger",
+    "Branch",
+    "CommitSummary",
+    "PaginatedResponse",
+    "Comment",
+    "Label",
+    "SshKey",
+    "User",
+    "CIConfig",
+]

git_alternative/ci.py

@@ -0,0 +1,162 @@
+"""CI pipeline configuration parser for .forge/ci.yml files."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import yaml
+
+from git_alternative.exceptions import ForgeValidationError
+from git_alternative.models import CIConfig, CIJobDefinition, CIJobStep, CITrigger
+
+
+def parse_ci_config(yaml_str: str) -> CIConfig:
+    """Parse a ``.forge/ci.yml`` pipeline configuration string.
+
+    Args:
+        yaml_str: YAML content of the CI configuration file.
+
+    Returns:
+        A :class:`~git_alternative.models.CIConfig` instance representing the
+        parsed pipeline definition.
+
+    Raises:
+        ForgeValidationError: If the YAML is invalid or required fields are
+            missing.
+
+    Example:
+        >>> config = parse_ci_config('''
+        ... name: Build and Test
+        ... on:
+        ...   push:
+        ...     branches: [main]
+        ... jobs:
+        ...   test:
+        ...     name: Run Tests
+        ...     runs-on: ubuntu-22.04
+        ...     steps:
+        ...       - name: Run tests
+        ...         run: cargo test
+        ... ''')
+        >>> config.name
+        'Build and Test'
+        >>> "test" in config.jobs
+        True
+    """
+    try:
+        data = yaml.safe_load(yaml_str)
+    except yaml.YAMLError as exc:
+        raise ForgeValidationError(f"Invalid YAML in CI config: {exc}") from exc
+
+    if not isinstance(data, dict):
+        raise ForgeValidationError("CI config must be a YAML mapping")
+
+    name = data.get("name")
+    if not name:
+        raise ForgeValidationError("CI config missing required field: 'name'")
+
+    trigger = _parse_trigger(data.get("on", {}))
+    jobs = _parse_jobs(data.get("jobs", {}))
+
+    return CIConfig(name=str(name), trigger=trigger, jobs=jobs)
+
+
+def _parse_trigger(on_data: Any) -> CITrigger:
+    """Parse the ``on:`` trigger section of a CI config.
+
+    Args:
+        on_data: The value of the ``on`` key in the YAML document.
+
+    Returns:
+        A :class:`~git_alternative.models.CITrigger` instance.
+    """
+    push_branches: list[str] = []
+    pr_branches: list[str] = []
+
+    if isinstance(on_data, dict):
+        push = on_data.get("push", {})
+        if isinstance(push, dict):
+            push_branches = push.get("branches", [])
+
+        pr = on_data.get("pull_request", {})
+        if isinstance(pr, dict):
+            pr_branches = pr.get("branches", [])
+
+    return CITrigger(push_branches=push_branches, pr_branches=pr_branches)
+
+
+def _parse_jobs(jobs_data: Any) -> dict[str, CIJobDefinition]:
+    """Parse the ``jobs:`` section of a CI config.
+
+    Args:
+        jobs_data: The value of the ``jobs`` key in the YAML document.
+
+    Returns:
+        A mapping of job ID to :class:`~git_alternative.models.CIJobDefinition`.
+
+    Raises:
+        ForgeValidationError: If a job definition is missing required fields.
+    """
+    if not isinstance(jobs_data, dict):
+        return {}
+
+    result: dict[str, CIJobDefinition] = {}
+    for job_id, job_data in jobs_data.items():
+        if not isinstance(job_data, dict):
+            raise ForgeValidationError(f"Job '{job_id}' must be a mapping")
+
+        runs_on = job_data.get("runs-on")
+        if not runs_on:
+            raise ForgeValidationError(f"Job '{job_id}' missing required field: 'runs-on'")
+
+        job_name = job_data.get("name", job_id)
+        needs = job_data.get("needs", [])
+        if isinstance(needs, str):
+            needs = [needs]
+
+        steps = _parse_steps(job_id, job_data.get("steps", []))
+
+        result[job_id] = CIJobDefinition(
+            name=str(job_name),
+            runs_on=str(runs_on),
+            steps=steps,
+            needs=list(needs),
+        )
+
+    return result
+
+
+def _parse_steps(job_id: str, steps_data: Any) -> list[CIJobStep]:
+    """Parse the ``steps:`` list within a job definition.
+
+    Args:
+        job_id: The job identifier (used in error messages).
+        steps_data: The value of the ``steps`` key for this job.
+
+    Returns:
+        A list of :class:`~git_alternative.models.CIJobStep` instances.
+
+    Raises:
+        ForgeValidationError: If a step is missing a ``name`` field.
+    """
+    if not isinstance(steps_data, list):
+        return []
+
+    steps: list[CIJobStep] = []
+    for i, step in enumerate(steps_data):
+        if not isinstance(step, dict):
+            raise ForgeValidationError(
+                f"Job '{job_id}' step {i} must be a mapping"
+            )
+        step_name = step.get("name", f"step-{i}")
+        with_params = step.get("with", {}) or {}
+        steps.append(
+            CIJobStep(
+                name=str(step_name),
+                run=step.get("run"),
+                uses=step.get("uses"),
+                with_params=dict(with_params),
+            )
+        )
+
+    return steps

git_alternative/cli.py

@@ -0,0 +1,117 @@
+"""Minimal CLI entry point for the git-alternative package."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="forge",
+        description="forge — keyboard-driven Git collaboration platform CLI",
+    )
+    parser.add_argument("--version", action="version", version="git-alternative 0.2.1")
+    parser.add_argument("--host", default=None, help="Forge instance URL")
+    parser.add_argument("--token", default=None, help="Personal access token")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+
+    sub = parser.add_subparsers(dest="command")
+
+    # fingerprint sub-command
+    fp_parser = sub.add_parser("fingerprint", help="Compute SSH key fingerprint")
+    fp_parser.add_argument("key", help="SSH public key string or path to key file")
+
+    # ci validate sub-command
+    ci_parser = sub.add_parser("ci", help="CI configuration utilities")
+    ci_sub = ci_parser.add_subparsers(dest="ci_command")
+    validate_parser = ci_sub.add_parser("validate", help="Validate a .forge/ci.yml file")
+    validate_parser.add_argument("file", help="Path to ci.yml file")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for the ``forge`` CLI.
+
+    Args:
+        argv: Argument list (defaults to ``sys.argv[1:]``).
+
+    Returns:
+        Exit code (0 = success, non-zero = error).
+    """
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "fingerprint":
+        return _cmd_fingerprint(args)
+    if args.command == "ci":
+        return _cmd_ci(args)
+
+    parser.print_help()
+    return 0
+
+
+def _cmd_fingerprint(args: argparse.Namespace) -> int:
+    """Handle the ``forge fingerprint`` sub-command."""
+    from git_alternative.utils import compute_key_fingerprint
+    from git_alternative.exceptions import ForgeValidationError
+
+    key_input = args.key
+    # If it looks like a file path, try to read it
+    if not key_input.startswith("ssh-") and not key_input.startswith("ecdsa-"):
+        try:
+            with open(key_input) as fh:
+                key_input = fh.read().strip()
+        except OSError:
+            pass  # treat as literal key string
+
+    try:
+        fp = compute_key_fingerprint(key_input)
+    except ForgeValidationError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+    if args.json:
+        print(json.dumps({"fingerprint": fp}))
+    else:
+        print(fp)
+    return 0
+
+
+def _cmd_ci(args: argparse.Namespace) -> int:
+    """Handle the ``forge ci`` sub-commands."""
+    if args.ci_command == "validate":
+        return _cmd_ci_validate(args)
+    # No sub-command given
+    print("Usage: forge ci <validate>", file=sys.stderr)
+    return 1
+
+
+def _cmd_ci_validate(args: argparse.Namespace) -> int:
+    """Handle the ``forge ci validate`` sub-command."""
+    from git_alternative.ci import CiConfig
+    from git_alternative.exceptions import ForgeValidationError
+
+    try:
+        with open(args.file) as fh:
+            content = fh.read()
+    except OSError as exc:
+        print(f"Error reading file: {exc}", file=sys.stderr)
+        return 1
+
+    try:
+        config = CiConfig.from_yaml(content)
+    except ForgeValidationError as exc:
+        print(f"Invalid CI config: {exc}", file=sys.stderr)
+        return 1
+
+    errors = config.validate()
+    if errors:
+        for err in errors:
+            print(f"  - {err}", file=sys.stderr)
+        return 1
+
+    print(f"✓ CI config '{config.name}' is valid ({len(config.jobs)} job(s))")
+    return 0

git_alternative/client.py

@@ -0,0 +1,72 @@
+"""Main ForgeClient entry point."""
+
+from __future__ import annotations
+
+from git_alternative.http import HttpClient
+from git_alternative.resources.issues import IssuesResource
+from git_alternative.resources.pipelines import PipelinesResource
+from git_alternative.resources.pulls import PullsResource
+from git_alternative.resources.repos import ReposResource
+from git_alternative.resources.users import UsersResource
+from git_alternative.resources.webhooks import WebhooksResource
+
+
+class ForgeClient:
+    """Python SDK client for the Forge Git collaboration platform.
+
+    Provides access to all Forge API resources through sub-clients.
+
+    Args:
+        host: Base URL of the Forge instance (e.g., ``https://forge.example.com``).
+        token: Personal Access Token for authentication. If omitted, only
+            public endpoints are accessible.
+        timeout: HTTP request timeout in seconds (default: 30).
+
+    Example:
+        >>> client = ForgeClient(
+        ...     host="https://forge.example.com",
+        ...     token="pat_your_token",
+        ... )
+        >>> repos = client.repos.list(owner="alice")
+    """
+
+    def __init__(
+        self,
+        host: str,
+        token: str | None = None,
+        timeout: int = 30,
+    ) -> None:
+        self._http = HttpClient(host=host, token=token, timeout=timeout)
+        self.repos = ReposResource(self._http)
+        self.issues = IssuesResource(self._http)
+        self.pulls = PullsResource(self._http)
+        self.pipelines = PipelinesResource(self._http)
+        self.users = UsersResource(self._http)
+        self.webhooks = WebhooksResource(self._http)
+
+    @property
+    def host(self) -> str:
+        """The base URL of the connected Forge instance."""
+        return self._http.host
+
+    def authenticate(self, username: str, password: str) -> str:
+        """Authenticate with username and password, returning a session token.
+
+        Args:
+            username: Forge username.
+            password: Account password.
+
+        Returns:
+            A session token string.
+
+        Raises:
+            ForgeAuthError: If credentials are invalid.
+        """
+        data = self._http.post(
+            "/api/v1/auth/login",
+            json={"username": username, "password": password},
+        )
+        token = data.get("token", "")
+        self._http.token = token
+        self._http._session.headers["Authorization"] = f"Bearer {token}"
+        return token

git_alternative/exceptions.py

@@ -0,0 +1,43 @@
+"""Custom exceptions for the git-alternative SDK."""
+
+
+class ForgeError(Exception):
+    """Base exception for all Forge API errors."""
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+
+    def __str__(self) -> str:
+        if self.status_code:
+            return f"[HTTP {self.status_code}] {self.message}"
+        return self.message
+
+
+class ForgeAuthError(ForgeError):
+    """Raised when authentication fails (401 Unauthorized)."""
+
+
+class ForgeNotFoundError(ForgeError):
+    """Raised when a resource is not found (404 Not Found)."""
+
+
+class ForgeConflictError(ForgeError):
+    """Raised when a resource conflict occurs (409 Conflict)."""
+
+
+class ForgeValidationError(ForgeError):
+    """Raised when request validation fails (422 Unprocessable Entity)."""
+
+
+class ForgeRateLimitError(ForgeError):
+    """Raised when the API rate limit is exceeded (429 Too Many Requests)."""
+
+
+class ForgeServerError(ForgeError):
+    """Raised when the server returns a 5xx error."""
+
+
+class ForgeInvalidSshKeyError(ForgeError):
+    """Raised when an SSH public key is malformed or invalid."""

git_alternative/http.py

@@ -0,0 +1,137 @@
+"""Low-level HTTP client for the Forge REST API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import requests
+
+from git_alternative.exceptions import (
+    ForgeAuthError,
+    ForgeConflictError,
+    ForgeError,
+    ForgeNotFoundError,
+    ForgeRateLimitError,
+    ForgeServerError,
+    ForgeValidationError,
+)
+
+_DEFAULT_TIMEOUT = 30
+
+
+class HttpClient:
+    """Thin wrapper around :mod:`requests` for Forge API calls.
+
+    Args:
+        host: Base URL of the Forge instance (e.g. ``"https://forge.example.com"``).
+        token: Personal Access Token for Bearer authentication.
+        timeout: Request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        host: str,
+        token: str | None = None,
+        timeout: int = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self.host = host.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self._session = requests.Session()
+        if token:
+            self._session.headers["Authorization"] = f"Bearer {token}"
+        self._session.headers["Content-Type"] = "application/json"
+        self._session.headers["Accept"] = "application/json"
+
+    def _url(self, path: str) -> str:
+        return f"{self.host}{path}"
+
+    def _raise_for_status(self, response: requests.Response) -> None:
+        """Map HTTP error codes to typed Forge exceptions.
+
+        Args:
+            response: The :class:`requests.Response` to inspect.
+
+        Raises:
+            ForgeAuthError: On 401.
+            ForgeNotFoundError: On 404.
+            ForgeConflictError: On 409.
+            ForgeValidationError: On 422.
+            ForgeRateLimitError: On 429.
+            ForgeServerError: On 5xx.
+            ForgeError: On any other 4xx.
+        """
+        if response.ok:
+            return
+
+        try:
+            body = response.json()
+            message = body.get("message") or body.get("error") or response.text
+        except Exception:
+            message = response.text or response.reason
+
+        code = response.status_code
+        if code == 401:
+            raise ForgeAuthError(message, status_code=code)
+        if code == 404:
+            raise ForgeNotFoundError(message, status_code=code)
+        if code == 409:
+            raise ForgeConflictError(message, status_code=code)
+        if code == 422:
+            raise ForgeValidationError(message, status_code=code)
+        if code == 429:
+            raise ForgeRateLimitError(message, status_code=code)
+        if code >= 500:
+            raise ForgeServerError(message, status_code=code)
+        raise ForgeError(message, status_code=code)
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        """Perform a GET request.
+
+        Args:
+            path: API path (e.g. ``"/api/v1/repos/alice/my-repo"``).
+            params: Optional query parameters.
+
+        Returns:
+            Parsed JSON response body.
+        """
+        resp = self._session.get(self._url(path), params=params, timeout=self.timeout)
+        self._raise_for_status(resp)
+        return resp.json()
+
+    def post(self, path: str, json: dict[str, Any] | None = None) -> Any:
+        """Perform a POST request.
+
+        Args:
+            path: API path.
+            json: Request body as a dictionary.
+
+        Returns:
+            Parsed JSON response body.
+        """
+        resp = self._session.post(self._url(path), json=json, timeout=self.timeout)
+        self._raise_for_status(resp)
+        return resp.json()
+
+    def patch(self, path: str, json: dict[str, Any] | None = None) -> Any:
+        """Perform a PATCH request.
+
+        Args:
+            path: API path.
+            json: Request body as a dictionary.
+
+        Returns:
+            Parsed JSON response body.
+        """
+        resp = self._session.patch(self._url(path), json=json, timeout=self.timeout)
+        self._raise_for_status(resp)
+        return resp.json()
+
+    def delete(self, path: str) -> None:
+        """Perform a DELETE request.
+
+        Args:
+            path: API path.
+        """
+        resp = self._session.delete(self._url(path), timeout=self.timeout)
+        self._raise_for_status(resp)

git_alternative/managers/__init__.py

@@ -0,0 +1 @@
+"""Resource manager modules for the Forge SDK."""