git-alternative 0.2.2__tar.gz

git_alternative-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 AgentSoft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

git_alternative-0.2.2/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: git-alternative
+Version: 0.2.2
+Summary: A Python SDK and CLI toolkit for Forge — a keyboard-driven, self-hosted Git collaboration platform
+License: MIT
+License-File: LICENSE
+Keywords: git,forge,collaboration,devtools,cli
+Author: AgentSoft
+Author-email: agentsoft@example.com
+Requires-Python: >=3.9,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Version Control
+Requires-Dist: pyyaml (>=6.0,<7.0)
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Requires-Dist: tomli (>=2.0,<3.0) ; python_version < "3.11"
+Project-URL: Homepage, https://github.com/agentsoft/git-alternative
+Project-URL: Repository, https://github.com/agentsoft/git-alternative
+Description-Content-Type: text/markdown
+
+# git-alternative
+
+A Python SDK and CLI toolkit for interacting with **Forge** — a keyboard-driven, self-hosted Git collaboration platform. This package provides a clean Python API for managing repositories, issues, pull requests, CI pipelines, and more via the Forge REST API.
+
+## Installation
+
+

git_alternative-0.2.2/README.md

@@ -0,0 +1,6 @@
+# git-alternative
+
+A Python SDK and CLI toolkit for interacting with **Forge** — a keyboard-driven, self-hosted Git collaboration platform. This package provides a clean Python API for managing repositories, issues, pull requests, CI pipelines, and more via the Forge REST API.
+
+## Installation
+

git_alternative-0.2.2/pyproject.toml

@@ -0,0 +1,61 @@
+[tool.poetry]
+name = "git-alternative"
+version = "0.2.2"
+description = "A Python SDK and CLI toolkit for Forge — a keyboard-driven, self-hosted Git collaboration platform"
+authors = ["AgentSoft <agentsoft@example.com>"]
+readme = "README.md"
+license = "MIT"
+homepage = "https://github.com/agentsoft/git-alternative"
+repository = "https://github.com/agentsoft/git-alternative"
+keywords = ["git", "forge", "collaboration", "devtools", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Version Control",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+packages = [{include = "git_alternative", from = "src"}]
+
+[tool.poetry.dependencies]
+python = "^3.9"
+requests = "^2.31.0"
+pyyaml = "^6.0"
+tomli = {version = "^2.0", python = "<3.11"}
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.4.0"
+pytest-cov = "^4.1.0"
+ruff = "^0.1.0"
+responses = "^0.24.0"
+
+[tool.poetry.scripts]
+forge = "git_alternative.cli:main"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=git_alternative --cov-report=term-missing --cov-fail-under=80"
+
+[tool.coverage.run]
+source = ["src/git_alternative"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+show_missing = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+ignore = ["E501"]

git_alternative-0.2.2/src/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-0.2.2/src/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-0.2.2/src/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-0.2.2/src/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-0.2.2/src/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."""