quoll-cli 0.2.0__py3-none-any.whl

quoll/main.py

@@ -0,0 +1,50 @@
+from importlib.metadata import version
+
+import typer
+
+from quoll.commands import add, cd, ci, docker, k8s, remove
+from quoll.commands.add_secret import app as add_secret_app
+from quoll.commands.new import new
+from quoll.console import console
+
+app = typer.Typer(
+    name="quoll",
+    help="Production-grade CI, Dockerfiles, Helm charts and delivery for any repository, kept in sync with quoll.toml.",
+    no_args_is_help=True,
+)
+
+
+def _version(value: bool) -> None:
+    if value:
+        console.print(f"quoll {version('quoll-cli')}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    _: bool = typer.Option(False, "--version", callback=_version, is_eager=True, help="Show quoll's version."),
+) -> None:
+    """Production-grade CI, Dockerfiles, Helm charts and delivery for any repository, kept in sync with quoll.toml."""
+
+app.command("new")(new)
+app.add_typer(add.app, name="add")
+app.add_typer(remove.app, name="remove")
+app.add_typer(ci.app, name="ci")
+app.add_typer(docker.app, name="docker")
+app.add_typer(cd.app, name="cd")
+app.add_typer(k8s.app, name="k8s")
+app.add_typer(add_secret_app, name="add-secret")
+# Kept for scripts written against 0.1.x.
+app.command("init-ci", hidden=True, help="Alias of `quoll ci init`.")(ci.init)
+
+
+@app.command("init", hidden=True, context_settings={"allow_extra_args": True, "ignore_unknown_options": True})
+@app.command("create-project", hidden=True, context_settings={"allow_extra_args": True, "ignore_unknown_options": True})
+def _replaced() -> None:
+    """The scaffolding of 0.1.x."""
+    console.print("[red]Error:[/red] replaced by [bold]quoll new[/bold], e.g. quoll new shop --front angular "
+                  "--back express (see quoll new --help).")
+    raise typer.Exit(1)
+
+if __name__ == "__main__":
+    app()

quoll/platforms/__init__.py

@@ -0,0 +1,62 @@
+"""Code hosting platforms: where the repository lives and the CI/CD pipelines run.
+
+Each platform is a sub-package exposing `platform`, a `quoll.platforms.base.Platform`. The project's platform is
+`platform` in the [project] section of quoll.toml, detected from the git remote.
+"""
+from __future__ import annotations
+
+import importlib
+import re
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+from quoll.platforms.base import Platform, PlatformError, Remote
+
+__all__ = ["NAMES", "Platform", "PlatformError", "Remote", "detect", "get", "hosting", "parse_remote", "remote"]
+
+NAMES = ("github", "gitlab")
+
+
+def get(name: str) -> Platform:
+    if name not in NAMES:
+        raise KeyError(f"unknown platform '{name}' (expected one of: {', '.join(NAMES)})")
+    return importlib.import_module(f"quoll.platforms.{name}").platform
+
+
+def parse_remote(url: str) -> Optional[Remote]:
+    """Host and repository path of a git remote URL (https, ssh or scp-like)."""
+    m = re.match(r"^(?:[a-z+]+://)?(?:[^@/]+@)?([^/:]+)(?::\d+)?[:/](.+?)(?:\.git)?/?$", url.strip())
+    if not m or "/" not in m.group(2):
+        return None
+    return Remote(host=m.group(1).lower(), path=m.group(2))
+
+
+def remote(project_dir: Path) -> Optional[Remote]:
+    """Where `origin` points to."""
+    try:
+        result = subprocess.run(
+            ["git", "remote", "get-url", "origin"], cwd=project_dir, capture_output=True, text=True, timeout=5
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return parse_remote(result.stdout) if result.returncode == 0 else None
+
+
+def hosting(origin: Remote) -> Optional[str]:
+    """The platform serving `origin`, when its host tells (github.com, gitlab.com, gitlab.<company>...)."""
+    if origin.host == "github.com":
+        return "github"
+    if "gitlab" in origin.host:
+        return "gitlab"
+    return None
+
+
+def detect(project_dir: Path, origin: Optional[Remote] = None) -> str:
+    """The platform hosting the project: from the remote's host, else from the pipelines already there."""
+    hosted = hosting(origin) if origin else None
+    if hosted:
+        return hosted
+    if (project_dir / ".gitlab-ci.yml").exists() and not (project_dir / ".github" / "workflows").is_dir():
+        return "gitlab"
+    return "github"

quoll/platforms/base.py

@@ -0,0 +1,103 @@
+"""The contract every code hosting platform implements.
+
+A platform knows where its pipelines live and how to render them from quoll.toml (CI from [ci], delivery from
+[cd]), and talks to its API to create repositories, store CI secrets and protect branches.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Dict, List, Optional, Sequence, Tuple, Union
+
+if TYPE_CHECKING:
+    from quoll.cd.config import CDConfig
+    from quoll.ci.config import CIConfig
+    from quoll.files import PlannedFile
+    from quoll.workspace import Delivery, Repo
+
+
+class PlatformError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class Remote:
+    """Where a repository is hosted, e.g. ("github.com", "acme/api") or ("gitlab.com", "acme/backend/api")."""
+
+    host: str
+    # owner/repo on GitHub; group/[subgroups/]project on GitLab.
+    path: str
+
+    @property
+    def namespace(self) -> str:
+        return self.path.rsplit("/", 1)[0] if "/" in self.path else ""
+
+    @property
+    def name(self) -> str:
+        return self.path.rsplit("/", 1)[-1]
+
+
+@dataclass(frozen=True)
+class Repo:
+    path: str
+    clone_url: str
+    web_url: str
+
+
+class PlatformAPI(ABC):
+    @abstractmethod
+    def create_repo(self, name: str, private: bool = True) -> Repo:
+        """Create an empty repository in the configured organization/group, or the user's namespace."""
+
+    @abstractmethod
+    def set_secrets(self, repo: str, secrets: Dict[str, str]) -> None:
+        """Store CI secrets (GitHub) / masked CI/CD variables (GitLab) on the repository at path `repo`."""
+
+    def ensure_schedule(self, repo: str, branch: str, cron: str) -> bool:
+        """Create or update the schedule running the security scans. False when the pipeline file already holds
+        it (GitHub's `on: schedule`)."""
+        return False
+
+    @abstractmethod
+    def protect_branch(
+        self, repo: str, branch: str, required_checks: Sequence[str] = (), required_reviews: int = 0
+    ) -> List[str]:
+        """Forbid direct pushes and require a green pipeline (and reviews) to merge. Returns warnings."""
+
+
+class Platform(ABC):
+    name: str
+    label: str
+    # What the platform calls the values `quoll` stores for the CI, e.g. "secrets".
+    secrets_label: str
+    # Registries `quoll cd` can push to; the first is the default.
+    registries: Tuple[str, ...]
+    # Status checks branch protection requires, when the platform can't require "the pipeline" as a whole.
+    required_checks: Tuple[str, ...] = ()
+    # Scheduled pipelines are configured through the API rather than in the pipeline file.
+    schedules_via_api: bool = False
+
+    @abstractmethod
+    def ci_files(self, project_dir: Path, cfg: Union[CIConfig, Repo]) -> List[PlannedFile]:
+        """The CI pipeline of a project or a workspace (`Repo`), then files only created when missing."""
+
+    @abstractmethod
+    def cd_files(self, project_dir: Path, cfg: Union[CDConfig, List[Delivery]]) -> List[PlannedFile]:
+        """The delivery pipeline of a project, or of the workspace members' deliveries."""
+
+    @abstractmethod
+    def default_image(self, remote: Optional[Remote], registry: str, fallback_name: str, member: str = "") -> str:
+        """Image name `quoll cd` suggests for `registry` (for the workspace `member`, if any)."""
+
+    @abstractmethod
+    def registry_secrets(self, registry: str) -> List[str]:
+        """Secrets the user must set for `registry` (none for the platform's own registry)."""
+
+    @abstractmethod
+    def merge_gate(self) -> str:
+        """How to require the pipeline before merging, shown after `quoll ci init`."""
+
+    @abstractmethod
+    def api(self, host: Optional[str] = None) -> PlatformAPI:
+        """Client for the platform's API (on `host` for self-managed instances)."""

quoll/platforms/github/__init__.py

@@ -0,0 +1,4 @@
+"""GitHub: GitHub Actions workflows, Dependabot, GHCR, and the REST API."""
+from quoll.platforms.github.platform import GitHub
+
+platform = GitHub()

quoll/platforms/github/actions.py

@@ -0,0 +1,78 @@
+"""GitHub Actions used by the generated workflows."""
+
+# Referenced by version here; workflows pin them to the commit SHA below (supply-chain hardening: a tag can be
+# moved, a commit can't), with the version as a comment. Dependabot (github-actions ecosystem) proposes updates.
+ACTIONS = {
+    "checkout": "actions/checkout@v7",
+    "setup-python": "actions/setup-python@v7",
+    "setup-node": "actions/setup-node@v7",
+    "setup-go": "actions/setup-go@v7",
+    "setup-java": "actions/setup-java@v6",
+    "setup-gradle": "gradle/actions/setup-gradle@v6",
+    "setup-dotnet": "actions/setup-dotnet@v6",
+    "setup-php": "shivammathur/setup-php@v2",
+    "setup-ruby": "ruby/setup-ruby@v1",
+    "setup-rust": "actions-rust-lang/setup-rust-toolchain@v2",
+    "install-tool": "taiki-e/install-action@v2",
+    "cache": "actions/cache@v6",
+    # No floating major tag upstream since v8.
+    "setup-uv": "astral-sh/setup-uv@v10.3.3",
+    "setup-pnpm": "pnpm/action-setup@v6",
+    "setup-bun": "oven-sh/setup-bun@v2",
+    "golangci-lint": "golangci/golangci-lint-action@v9",
+    "codecov": "codecov/codecov-action@v7",
+    "setup-buildx": "docker/setup-buildx-action@v4",
+    "build-push": "docker/build-push-action@v7",
+    "setup-qemu": "docker/setup-qemu-action@v4",
+    "metadata": "docker/metadata-action@v6",
+    "login": "docker/login-action@v4",
+    # No major-version tag upstream: dependabot bumps it.
+    "trivy": "aquasecurity/trivy-action@v0.36.0",
+    "sonar": "SonarSource/sonarqube-scan-action@v8",
+    "codeql-init": "github/codeql-action/init@v4",
+    "codeql-analyze": "github/codeql-action/analyze@v4",
+    "junit-report": "mikepenz/action-junit-report@v6",
+    "upload-artifact": "actions/upload-artifact@v7",
+    "attest": "actions/attest@v4",
+    "setup-helm": "azure/setup-helm@v5",
+}
+
+# Commit of each version above. Refresh with:
+#   gh api repos/<owner>/<repo>/commits/<version> --jq .sha
+PINS = {
+    "SonarSource/sonarqube-scan-action@v8": "59202af334b4ba7b5db01b701b8e79f8b3bef0f4",
+    "actions-rust-lang/setup-rust-toolchain@v2": "a188e68d0fd2bd36ad51dccb2b07ba6e75105f30",
+    "actions/cache@v6": "55cc8345863c7cc4c66a329aec7e433d2d1c52a9",
+    "actions/checkout@v7": "3d3c42e5aac5ba805825da76410c181273ba90b1",
+    "actions/setup-dotnet@v6": "0f4a354dd5547a28c70b7853dbd95d5b67886e73",
+    "actions/setup-go@v7": "b7ad1dad31e06c5925ef5d2fc7ad053ef454303e",
+    "actions/setup-java@v6": "b843ebf9b913146b38da2eaa7aeddf76074ae1ad",
+    "actions/setup-node@v7": "949feb2413d6458794dcd2491c4babbbce0c15c1",
+    "actions/setup-python@v7": "6d4fd22b20465ccc0f7354476588e8df7c9ca0e0",
+    "aquasecurity/trivy-action@v0.36.0": "ed142fd0673e97e23eac54620cfb913e5ce36c25",
+    "astral-sh/setup-uv@v10.3.3": "68559e99cc807c1eb7e9238fd43a15bba460eec2",
+    "codecov/codecov-action@v7": "303a32d7a59b442fa8d48b6a1cc6825c09c847a5",
+    "docker/build-push-action@v7": "c3c9e263c25d99ce0380d002d59b67737d91b0dc",
+    "docker/login-action@v4": "8aa5831fb8d48d8f76594c7ddde61ae58019f550",
+    "docker/metadata-action@v6": "dc802804100637a589fabce1cb79ff13a1411302",
+    "docker/setup-buildx-action@v4": "f87e5991a6d7451dcb8d9637bfbc97413f497069",
+    "docker/setup-qemu-action@v4": "99012661954931238ded8c8b007157a8430204e1",
+    "github/codeql-action/analyze@v4": "33d7b85da1a04171e211befe2c739303b9a4c066",
+    "github/codeql-action/init@v4": "33d7b85da1a04171e211befe2c739303b9a4c066",
+    "actions/upload-artifact@v7": "cf430e030ddbb5b0abf93d22962f4752f3646cd9",
+    "azure/setup-helm@v5": "2f5e7bc67f1f9972ab16657bb795f36d8f04de0e",
+    "actions/attest@v4": "1e69f48acb82d1966a394da916b4c1698aa569d6",
+    "mikepenz/action-junit-report@v6": "a16be3a69023e9bd7e748ede768b3282ea7b30ce",
+    "golangci/golangci-lint-action@v9": "ba0d7d2ec06a0ea1cb5fa41b2e4a3ab91d21278a",
+    "gradle/actions/setup-gradle@v6": "8da46b539cd8fe6ab27ca75128919a18d757604c",
+    "oven-sh/setup-bun@v2": "0c5077e51419868618aeaa5fe8019c62421857d6",
+    "pnpm/action-setup@v6": "73e46992e05b19abd31f2f3c20e0e7370d762115",
+    "ruby/setup-ruby@v1": "b3aaceaef7e0ee231b499e7b5f49c03fc1d32199",
+    "shivammathur/setup-php@v2": "eb7c497e18156a6bbabfef1d3a82760b9eda3962",
+    "taiki-e/install-action@v2": "cfdb7ed4ccc7c7dce37759eae89dc5674b469b39",
+}
+
+
+def gha_cache_scope(project: str) -> str:
+    """BuildKit's GitHub Actions cache, one scope per project: a monorepo's images don't evict each other's layers."""
+    return f"type=gha,scope={project or 'ci'}"

quoll/platforms/github/api.py

@@ -0,0 +1,124 @@
+"""GitHub REST API: repositories, Actions secrets, branch protection."""
+from __future__ import annotations
+
+import base64
+from typing import Dict, List, Sequence, Tuple
+
+import httpx
+
+from quoll.config.settings import settings
+from quoll.platforms.base import PlatformAPI, PlatformError, Repo
+
+GITHUB_API = "https://api.github.com"
+
+_ERROR_HINTS = {
+    401: "The token is invalid or expired (QUOLL_GITHUB_TOKEN, `gh auth login`, or ~/.config/quoll/config.toml).",
+    403: "The token lacks permissions: it needs the 'repo' scope.",
+    422: "The repository may already exist on GitHub.",
+}
+
+
+class GitHubError(PlatformError):
+    pass
+
+
+def github_client() -> httpx.Client:
+    return httpx.Client(
+        base_url=GITHUB_API,
+        headers={
+            "Authorization": f"Bearer {settings.github_token}",
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+        timeout=30,
+    )
+
+
+class GitHubAPI(PlatformAPI):
+    def create_repo(self, name: str, private: bool = True) -> Repo:
+        with github_client() as client:
+            endpoint = f"/orgs/{settings.github_org}/repos" if settings.github_org else "/user/repos"
+            response = client.post(
+                endpoint,
+                json={"name": name, "private": private, "auto_init": False, "description": "Scaffolded by quoll"},
+            )
+            _raise_for_status(response, "create the repository")
+            data = response.json()
+            return Repo(path=data.get("full_name", name), clone_url=data["clone_url"], web_url=data.get("html_url", ""))
+
+    def set_secrets(self, repo: str, secrets: Dict[str, str]) -> None:
+        """Encrypt and upload Actions secrets."""
+        repo = self._full_path(repo)
+        with github_client() as client:
+            key_id, public_key = _repo_public_key(client, repo)
+            for name, value in secrets.items():
+                response = client.put(
+                    f"/repos/{repo}/actions/secrets/{name}",
+                    json={"encrypted_value": _encrypt_secret(public_key, value), "key_id": key_id},
+                )
+                _raise_for_status(response, f"save the secret {name}")
+
+    def protect_branch(
+        self, repo: str, branch: str, required_checks: Sequence[str] = (), required_reviews: int = 0
+    ) -> List[str]:
+        repo = self._full_path(repo)
+        # Changes go through a pull request; approvals are on top (GitHub doesn't let authors approve their own:
+        # one required approval would lock a project with a single developer out of its default branch).
+        reviews = {"required_approving_review_count": required_reviews, "dismiss_stale_reviews": True}
+        with github_client() as client:
+            response = client.put(
+                f"/repos/{repo}/branches/{branch}/protection",
+                json={
+                    "required_status_checks": {"strict": True, "contexts": list(required_checks)},
+                    "enforce_admins": True,
+                    "required_pull_request_reviews": reviews,
+                    "restrictions": None,
+                    "required_linear_history": True,
+                    "allow_force_pushes": False,
+                    "allow_deletions": False,
+                },
+            )
+            if response.is_error:
+                raise GitHubError(f"GitHub {response.status_code} while protecting the branch {branch}.")
+        return []
+
+    def _full_path(self, repo: str) -> str:
+        """owner/repo; a bare name belongs to the configured organization, or to the authenticated user."""
+        if "/" in repo:
+            return repo
+        return f"{settings.github_org or _authenticated_user()}/{repo}"
+
+
+def _authenticated_user() -> str:
+    with github_client() as client:
+        response = client.get("/user")
+        if response.is_error:
+            raise GitHubError(f"GitHub {response.status_code} while reading the authenticated user.")
+        return response.json()["login"]
+
+
+def _repo_public_key(client: httpx.Client, repo: str) -> Tuple[str, str]:
+    response = client.get(f"/repos/{repo}/actions/secrets/public-key")
+    _raise_for_status(response, "read the secrets' public key")
+    data = response.json()
+    return data["key_id"], data["key"]
+
+
+def _encrypt_secret(public_key_b64: str, secret_value: str) -> str:
+    """Encrypt a secret using the repo's public key (libsodium sealed box)."""
+    try:
+        from nacl import public
+    except ImportError as exc:
+        raise RuntimeError("PyNaCl is required for secret encryption: pip install PyNaCl") from exc
+
+    sealed_box = public.SealedBox(public.PublicKey(base64.b64decode(public_key_b64)))
+    return base64.b64encode(sealed_box.encrypt(secret_value.encode("utf-8"))).decode("utf-8")
+
+
+def _raise_for_status(response: httpx.Response, action: str) -> None:
+    if response.is_error:
+        hint = _ERROR_HINTS.get(response.status_code, "")
+        msg = f"GitHub {response.status_code} while trying to {action}."
+        if hint:
+            msg += f" {hint}"
+        raise GitHubError(msg)