forge-publish 2.3.0__py3-none-any.whl

forge_publish/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("forge-publish")

forge_publish/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

forge_publish/cli.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from .client import ForgejoClient
+from .config import configure, load_config
+from .errors import ForgePublishError
+from .publishers import deb, generic, npm
+
+
+def _create_client(
+    *,
+    dry_run: bool,
+    insecure: bool,
+) -> ForgejoClient:
+    config = load_config(require_token=not dry_run)
+
+    if insecure and not dry_run:
+        click.echo(
+            "WARNING: TLS certificate verification is disabled.",
+            err=True,
+        )
+
+    return ForgejoClient(
+        config,
+        verify_tls=not insecure,
+    )
+
+
+@click.group()
+@click.version_option()
+def main():
+    """Publish packages to Forgejo package registries."""
+
+
+@main.command("config")
+@click.option(
+    "--url",
+    prompt="Forgejo URL",
+)
+@click.option(
+    "--owner",
+    prompt="Forgejo owner",
+)
+@click.option(
+    "--username",
+    prompt="Forgejo username",
+)
+def config_command(
+    url: str,
+    owner: str,
+    username: str,
+):
+    """Configure Forgejo credentials."""
+    try:
+        configure(
+            url=url,
+            owner=owner,
+            username=username,
+        )
+    except ForgePublishError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+@main.command("deb")
+@click.argument(
+    "file",
+    type=click.Path(
+        exists=True,
+        dir_okay=False,
+        path_type=Path,
+    ),
+)
+@click.option(
+    "--distribution",
+    "-d",
+    required=True,
+)
+@click.option(
+    "--component",
+    "-c",
+    required=True,
+)
+@click.option(
+    "--insecure",
+    is_flag=True,
+    help="Disable TLS certificate verification.",
+)
+@click.option("--dry-run", is_flag=True)
+def deb_command(
+    file: Path,
+    distribution: str,
+    component: str,
+    insecure: bool,
+    dry_run: bool,
+):
+    """Publish a Debian package."""
+    try:
+        client = _create_client(
+            dry_run=dry_run,
+            insecure=insecure,
+        )
+        deb.publish(
+            client=client,
+            file=file,
+            distribution=distribution,
+            component=component,
+            dry_run=dry_run,
+        )
+    except ForgePublishError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+@main.command("generic")
+@click.argument(
+    "file",
+    type=click.Path(
+        exists=True,
+        dir_okay=False,
+        path_type=Path,
+    ),
+)
+@click.option(
+    "--package",
+    "package_name",
+    required=True,
+    help="Generic package name.",
+)
+@click.option(
+    "--version",
+    required=True,
+    help="Package version.",
+)
+@click.option(
+    "--filename",
+    help="Filename stored in Forgejo.",
+)
+@click.option(
+    "--insecure",
+    is_flag=True,
+    help="Disable TLS certificate verification.",
+)
+@click.option("--dry-run", is_flag=True)
+def generic_command(
+    file: Path,
+    package_name: str,
+    version: str,
+    filename: str | None,
+    insecure: bool,
+    dry_run: bool,
+):
+    """Publish a Generic package."""
+    try:
+        client = _create_client(
+            dry_run=dry_run,
+            insecure=insecure,
+        )
+
+        generic.publish(
+            client=client,
+            file=file,
+            package_name=package_name,
+            version=version,
+            filename=filename,
+            dry_run=dry_run,
+        )
+    except ForgePublishError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+@main.command("npm")
+@click.argument(
+    "directory",
+    type=click.Path(
+        exists=True,
+        file_okay=False,
+        path_type=Path,
+    ),
+    default=".",
+)
+@click.option(
+    "--allow-pack-scripts",
+    is_flag=True,
+    help=(
+        "Execute npm pack lifecycle scripts (disabled by default). "
+        "Only use with trusted packages: background processes may access "
+        "later publication credentials."
+    ),
+)
+@click.option("--dry-run", is_flag=True)
+def npm_command(
+    directory: Path,
+    allow_pack_scripts: bool,
+    dry_run: bool,
+):
+    """Publish an NPM package (requires npm 11.0.0 or newer)."""
+    try:
+        client = _create_client(
+            dry_run=dry_run,
+            insecure=False,
+        )
+        npm.publish(
+            client=client,
+            directory=directory,
+            dry_run=dry_run,
+            allow_pack_scripts=allow_pack_scripts,
+        )
+    except ForgePublishError as exc:
+        raise click.ClickException(str(exc)) from exc

forge_publish/client.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import requests
+
+from .config import Config
+from .errors import ForgePublishError
+
+REQUEST_TIMEOUT = (10, 300)
+MAX_ERROR_MESSAGE_LENGTH = 500
+
+
+class ForgejoError(ForgePublishError):
+    """Raised when communication with Forgejo fails."""
+
+
+class ForgejoClient:
+    def __init__(
+        self,
+        config: Config,
+        *,
+        verify_tls: bool,
+    ):
+        self.config = config
+        self.verify_tls = verify_tls
+        self.session = requests.Session()
+
+        if config.token:
+            self.session.auth = (
+                config.username,
+                config.token,
+            )
+
+    def upload(
+        self,
+        url: str,
+        file: Path,
+        *,
+        dry_run: bool,
+    ) -> None:
+        if dry_run:
+            print()
+            print("DRY RUN")
+            print("-------")
+            print(f"PUT  : {url}")
+            print(f"FILE : {file}")
+            return
+
+        self._require_authentication()
+
+        try:
+            stream = file.open("rb")
+        except OSError as exc:
+            raise ForgejoError(f"Unable to read file: {file}") from exc
+
+        try:
+            with stream:
+                response = self.session.put(
+                    url,
+                    data=stream,
+                    timeout=REQUEST_TIMEOUT,
+                    verify=self.verify_tls,
+                    allow_redirects=False,
+                )
+        except requests.RequestException as exc:
+            raise ForgejoError(f"HTTP request failed: {exc}") from exc
+        except OSError as exc:
+            raise ForgejoError(f"Unable to read file: {file}") from exc
+
+        if 200 <= response.status_code < 300:
+            return
+
+        self._raise_error(response)
+
+    def delete(
+        self,
+        url: str,
+        *,
+        dry_run: bool,
+        ignore_404: bool,
+    ) -> None:
+        if dry_run:
+            print()
+            print("DRY RUN")
+            print("-------")
+            print(f"DELETE : {url}")
+            return
+
+        self._require_authentication()
+
+        try:
+            response = self.session.delete(
+                url,
+                timeout=REQUEST_TIMEOUT,
+                verify=self.verify_tls,
+                allow_redirects=False,
+            )
+        except requests.RequestException as exc:
+            raise ForgejoError(f"HTTP request failed: {exc}") from exc
+
+        if response.status_code == 404 and ignore_404:
+            return
+
+        if not 200 <= response.status_code < 300:
+            self._raise_error(response)
+
+    def _require_authentication(self) -> None:
+        if not self.config.token:
+            raise ForgejoError("No Forgejo token configured.")
+
+    @staticmethod
+    def _response_message(response: requests.Response) -> str:
+        message = ""
+
+        try:
+            payload: Any = response.json()
+        except ValueError:
+            payload = None
+
+        if isinstance(payload, dict):
+            for key in ("message", "error", "detail"):
+                value = payload.get(key)
+                if isinstance(value, str) and value.strip():
+                    message = value.strip()
+                    break
+
+        if not message:
+            message = response.text.strip()
+
+        if len(message) > MAX_ERROR_MESSAGE_LENGTH:
+            return message[:MAX_ERROR_MESSAGE_LENGTH] + "..."
+
+        return message
+
+    @classmethod
+    def _raise_error(cls, response: requests.Response) -> None:
+        if 300 <= response.status_code < 400:
+            raise ForgejoError(
+                f"HTTP {response.status_code}: Forgejo redirect refused. "
+                "Configure the canonical Forgejo URL and check proxy authentication."
+            )
+
+        reasons = {
+            400: "invalid package or request",
+            401: "authentication failed",
+            403: "permission denied",
+            404: "resource not found",
+            409: "package/file already exists",
+            413: "package/file is too large",
+            429: "too many requests",
+        }
+
+        if response.status_code >= 500:
+            reason = "Forgejo server error"
+        else:
+            reason = reasons.get(
+                response.status_code,
+                "Forgejo returned an error",
+            )
+
+        message = cls._response_message(response)
+        if message:
+            reason += f": {message}"
+
+        raise ForgejoError(f"HTTP {response.status_code}: {reason}")

forge_publish/config.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+import os
+import stat
+import tomllib
+from dataclasses import dataclass, field
+from getpass import getpass
+from urllib.parse import urlsplit
+
+import keyring
+import tomli_w
+from keyring.errors import KeyringError
+from platformdirs import user_config_path
+
+from .errors import ConfigurationError
+
+APP_NAME = "forge-publish"
+CONFIG_DIR = user_config_path(APP_NAME, appauthor=False)
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+KEYRING_SERVICE = "forge-publish"
+TOKEN_ENV_VAR = "FORGE_PUBLISH_TOKEN"
+
+
+@dataclass
+class Config:
+    url: str
+    owner: str
+    username: str
+    token: str | None = field(default=None, repr=False)
+
+    @property
+    def credential_name(self) -> str:
+        return f"{self.url}|{self.owner}|{self.username}"
+
+    def save(self) -> None:
+        data = {
+            "url": self.url,
+            "owner": self.owner,
+            "username": self.username,
+        }
+
+        try:
+            CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+            with CONFIG_FILE.open("wb") as file:
+                file.write(tomli_w.dumps(data).encode("utf-8"))
+        except OSError as exc:
+            raise ConfigurationError(
+                f"Unable to write configuration file: {CONFIG_FILE}"
+            ) from exc
+
+        try:
+            CONFIG_FILE.chmod(stat.S_IRUSR | stat.S_IWUSR)
+        except OSError:
+            # Permissions are best-effort and vary across platforms.
+            pass
+
+
+def _normalize_owner(owner: str) -> str:
+    normalized = owner.strip()
+
+    if not normalized:
+        raise ConfigurationError("Forgejo owner cannot be empty.")
+
+    if normalized in {".", ".."}:
+        raise ConfigurationError("Forgejo owner cannot be '.' or '..'.")
+
+    return normalized
+
+
+def _normalize_url(url: str) -> str:
+    normalized = url.strip().rstrip("/")
+
+    if "?" in normalized or "#" in normalized:
+        raise ConfigurationError(
+            "Forgejo URL must be a valid HTTPS URL without "
+            "credentials, query parameters, or fragments."
+        )
+
+    try:
+        parsed = urlsplit(normalized)
+        _port = parsed.port
+    except ValueError as exc:
+        raise ConfigurationError(
+            "Forgejo URL must be a valid HTTPS URL without "
+            "credentials, query parameters, or fragments."
+        ) from exc
+
+    if (
+        parsed.scheme != "https"
+        or not parsed.netloc
+        or not parsed.hostname
+        or parsed.username is not None
+        or parsed.password is not None
+        or any(character.isspace() for character in normalized)
+    ):
+        raise ConfigurationError(
+            "Forgejo URL must be a valid HTTPS URL without "
+            "credentials, query parameters, or fragments."
+        )
+
+    return normalized
+
+
+def _read_config_data() -> dict[str, object]:
+    if not CONFIG_FILE.exists():
+        raise ConfigurationError(
+            f"Configuration file does not exist: {CONFIG_FILE}\n"
+            "Run: forge-publish config"
+        )
+
+    try:
+        with CONFIG_FILE.open("rb") as file:
+            data = tomllib.load(file)
+    except UnicodeDecodeError as exc:
+        raise ConfigurationError(f"Invalid UTF-8 configuration: {CONFIG_FILE}") from exc
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigurationError(f"Invalid TOML configuration: {CONFIG_FILE}") from exc
+    except OSError as exc:
+        raise ConfigurationError(
+            f"Unable to read configuration file: {CONFIG_FILE}"
+        ) from exc
+
+    if not isinstance(data, dict):
+        raise ConfigurationError("Invalid configuration format.")
+
+    return data
+
+
+def _build_config(data: dict[str, object]) -> Config:
+    required = ("url", "owner", "username")
+    missing = [
+        field
+        for field in required
+        if not isinstance(data.get(field), str) or not str(data[field]).strip()
+    ]
+
+    if missing:
+        raise ConfigurationError("Missing configuration fields: " + ", ".join(missing))
+
+    return Config(
+        url=_normalize_url(str(data["url"])),
+        owner=_normalize_owner(str(data["owner"])),
+        username=str(data["username"]).strip(),
+    )
+
+
+def _get_keyring_token(config: Config) -> str | None:
+    try:
+        return keyring.get_password(
+            KEYRING_SERVICE,
+            config.credential_name,
+        )
+    except KeyringError:
+        return None
+
+
+def _set_keyring_token(config: Config, token: str) -> None:
+    try:
+        keyring.set_password(
+            KEYRING_SERVICE,
+            config.credential_name,
+            token,
+        )
+    except KeyringError as exc:
+        raise ConfigurationError(
+            "Unable to store the Forgejo token in the system keyring."
+        ) from exc
+
+
+def _prompt_token() -> str:
+    try:
+        token = getpass("Forgejo token: ").strip()
+    except EOFError as exc:
+        raise ConfigurationError(
+            f"No Forgejo token available. Set {TOKEN_ENV_VAR} or run "
+            "forge-publish config in an interactive terminal."
+        ) from exc
+
+    if not token:
+        raise ConfigurationError("Forgejo token cannot be empty.")
+
+    return token
+
+
+def load_config(*, require_token: bool) -> Config:
+    data = _read_config_data()
+    config = _build_config(data)
+
+    if not require_token:
+        return config
+
+    token = os.environ.get(TOKEN_ENV_VAR)
+    if not token:
+        token = _get_keyring_token(config)
+    if not token:
+        token = _prompt_token()
+
+    config.token = token
+    return config
+
+
+def configure(
+    url: str,
+    owner: str,
+    username: str,
+) -> None:
+    config = Config(
+        url=_normalize_url(url),
+        owner=_normalize_owner(owner),
+        username=username.strip(),
+    )
+
+    if not config.username:
+        raise ConfigurationError("Forgejo username cannot be empty.")
+
+    if os.environ.get(TOKEN_ENV_VAR):
+        config.save()
+
+        print(f"Configuration saved to {CONFIG_FILE}")
+        print(f"Forgejo token provided through {TOKEN_ENV_VAR}.")
+        return
+
+    token = _prompt_token()
+    _set_keyring_token(config, token)
+    config.save()
+
+    print(f"Configuration saved to {CONFIG_FILE}")
+    print("Forgejo token stored in the system keyring.")

forge_publish/errors.py

@@ -0,0 +1,10 @@
+class ForgePublishError(Exception):
+    """Base exception for expected forge-publish errors."""
+
+
+class ConfigurationError(ForgePublishError):
+    """Raised when local forge-publish configuration is invalid."""
+
+
+class PackageError(ForgePublishError):
+    """Raised when a package cannot be validated or prepared."""