conclear 1.0.0__py3-none-any.whl

conclear/__init__.py

@@ -0,0 +1,5 @@
+"""ConClear OCI image release application."""
+
+from conclear.identity import VERSION
+
+__version__ = VERSION

conclear/__main__.py

@@ -0,0 +1,6 @@
+"""Run ConClear as a Python module."""
+
+from conclear.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

conclear/_embedded_identity.py

@@ -0,0 +1,3 @@
+"""Generated source identity for this distribution build."""
+
+SOURCE_REVISION = "93692472fdb99cc2d3ea0e9c8aa8332d92d6ac63"

conclear/adapters/__init__.py

@@ -0,0 +1 @@
+"""Typed adapters for release tools and external services."""

conclear/adapters/base.py

@@ -0,0 +1,107 @@
+"""Shared command construction for external tool adapters."""
+
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Protocol
+
+from conclear.errors import InvalidInvocationError, OperationalError
+from conclear.process import (
+    CommandRequest,
+    OperationKind,
+    ProcessResult,
+)
+from conclear.tools import ResolvedTool
+
+
+def prepare_new_layout_path(layout_path: Path) -> None:
+    """Require an absent OCI-layout destination below an existing regular directory.
+
+    Tools that write `oci:` layouts neither create missing parents nor refuse an
+    existing layout, so every adapter that exports one applies the same
+    fail-closed preparation before the tool runs.
+    """
+    try:
+        layout_path.lstat()
+    except FileNotFoundError:
+        pass
+    except OSError as exc:
+        raise OperationalError(
+            f"Unable to inspect output layout {layout_path}"
+        ) from exc
+    else:
+        raise InvalidInvocationError(f"Output layout already exists: {layout_path}")
+    try:
+        layout_path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        if not layout_path.parent.is_dir() or layout_path.parent.is_symlink():
+            raise InvalidInvocationError(
+                f"Output layout parent is not a regular directory: {layout_path.parent}"
+            )
+    except OSError as exc:
+        raise OperationalError(
+            f"Unable to create output layout parent {layout_path.parent}"
+        ) from exc
+
+
+class Runner(Protocol):
+    """Narrow process runner boundary used by tool adapters."""
+
+    def run(self, request: CommandRequest) -> ProcessResult:
+        """Execute one fully specified external process."""
+        ...
+
+
+class ToolAdapter:
+    """Execute one immutable resolved tool through the central runner."""
+
+    def __init__(
+        self,
+        *,
+        tool: ResolvedTool,
+        runner: Runner,
+        environment: Mapping[str, str],
+        log_directory: Path,
+    ) -> None:
+        """Bind the adapter to a run-owned environment and log directory."""
+        self._tool = tool
+        self._runner = runner
+        self._environment = dict(environment)
+        self._log_directory = log_directory
+        self._sequence = 0
+
+    def _run(
+        self,
+        arguments: Sequence[str],
+        *,
+        operation: OperationKind = OperationKind.READ,
+        timeout_seconds: float,
+        retries: int = 0,
+        extra_environment: Mapping[str, str] | None = None,
+        secret_values: tuple[str, ...] = (),
+        secret_paths: tuple[Path, ...] = (),
+        cwd: Path | None = None,
+        stdout_artifact: Path | None = None,
+        max_artifact_bytes: int = 128 * 1024 * 1024,
+    ) -> ProcessResult:
+        self._tool.assert_unchanged()
+        environment = dict(self._environment)
+        if extra_environment is not None:
+            environment.update(extra_environment)
+        self._sequence += 1
+        return self._runner.run(
+            CommandRequest(
+                argv=(str(self._tool.path), *arguments),
+                environment=environment,
+                timeout_seconds=timeout_seconds,
+                operation=operation,
+                retries=retries,
+                log_path=(
+                    self._log_directory
+                    / f"{self._tool.name.value}-{self._sequence:04d}.json"
+                ),
+                secret_values=secret_values,
+                secret_paths=secret_paths,
+                cwd=cwd,
+                stdout_artifact=stdout_artifact,
+                max_artifact_bytes=max_artifact_bytes,
+            )
+        )

conclear/adapters/buildah.py

@@ -0,0 +1,128 @@
+"""Rootless Buildah OCI-layout adapter."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from conclear.adapters.base import ToolAdapter, prepare_new_layout_path
+from conclear.oci import OCIGraph, validate_layout
+from conclear.parsing import json_value, object_value
+from conclear.process import OperationKind
+from conclear.values import Platform
+
+
+@dataclass(frozen=True, slots=True)
+class BuildObservation:
+    """Observed result of one platform build."""
+
+    image_name: str
+    layout_path: Path
+    graph: OCIGraph
+    build_arguments: tuple[tuple[str, str], ...]
+
+
+class BuildahAdapter(ToolAdapter):
+    """Build one platform using run-specific containers storage."""
+
+    def info(self, *, root: Path, runroot: Path) -> dict[str, object]:
+        """Validate access to one isolated rootless Buildah storage."""
+        output = self._run(
+            (
+                "--root",
+                str(root),
+                "--runroot",
+                str(runroot),
+                "info",
+                "--format",
+                "{{json .}}",
+            ),
+            timeout_seconds=120,
+        ).stdout
+        return object_value(
+            json_value(output, label="Buildah info"), label="Buildah info"
+        )
+
+    def build(
+        self,
+        *,
+        root: Path,
+        runroot: Path,
+        containerfile: Path,
+        context: Path,
+        platform: Platform,
+        image_name: str,
+        layout_path: Path,
+        layout_reference: str,
+        source_epoch: int,
+        build_arguments: dict[str, str],
+        auth_file: Path | None,
+    ) -> BuildObservation:
+        """Build and export a digest-preserving OCI image layout."""
+        prepare_new_layout_path(layout_path)
+        arguments: list[str] = [
+            "--root",
+            str(root),
+            "--runroot",
+            str(runroot),
+            "build",
+            "--format",
+            "oci",
+            "--platform",
+            str(platform),
+            "--source-date-epoch",
+            str(source_epoch),
+            "--rewrite-timestamp",
+            "--pull=always",
+            # Labels describe this image, never its base (IG0431). Annotation
+            # inheritance stays on: Buildah writes the base annotations through it.
+            "--inherit-labels=false",
+            "--file",
+            str(containerfile),
+            "--tag",
+            image_name,
+        ]
+        if auth_file is not None:
+            arguments.extend(("--authfile", str(auth_file)))
+        for name, value in sorted(build_arguments.items()):
+            arguments.extend(("--build-arg", f"{name}={value}"))
+        arguments.append(str(context))
+        self._run(
+            arguments,
+            timeout_seconds=3600,
+            operation=OperationKind.WRITE,
+            secret_paths=(() if auth_file is None else (auth_file,)),
+        )
+        self._run(
+            (
+                "--root",
+                str(root),
+                "--runroot",
+                str(runroot),
+                "push",
+                "--format",
+                "oci",
+                image_name,
+                f"oci:{layout_path}:{layout_reference}",
+            ),
+            timeout_seconds=1800,
+            operation=OperationKind.WRITE,
+        )
+        graph = validate_layout(layout_path, reference=layout_reference)
+        return BuildObservation(
+            image_name=image_name,
+            layout_path=layout_path,
+            graph=graph,
+            build_arguments=tuple(sorted(build_arguments.items())),
+        )
+
+    def remove_storage(self, *, root: Path, runroot: Path) -> None:
+        """Remove every image in one run-owned Buildah storage root."""
+        self._run(
+            ("--root", str(root), "--runroot", str(runroot), "rm", "--all"),
+            timeout_seconds=300,
+            operation=OperationKind.WRITE,
+        )
+        self._run(
+            ("--root", str(root), "--runroot", str(runroot), "rmi", "--all"),
+            timeout_seconds=300,
+            operation=OperationKind.WRITE,
+        )

conclear/adapters/ci.py

@@ -0,0 +1,198 @@
+"""Typed observations from supported CI provider environments."""
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from urllib.parse import urlsplit, urlunsplit
+
+from conclear.errors import InvalidInvocationError
+from conclear.values import validate_source_revision
+
+
+@dataclass(frozen=True, slots=True)
+class CIContextAbsent:
+    """No supported CI provider marker was observed."""
+
+
+@dataclass(frozen=True, slots=True)
+class CIContextInvalid:
+    """A provider marker was observed without a usable complete context."""
+
+    provider: str | None
+    diagnostic: str
+
+
+@dataclass(frozen=True, slots=True)
+class ObservedCIContext:
+    """Narrow provider metadata observed from the current process environment."""
+
+    provider: str
+    server: str
+    repository: str
+    revision: str
+    run_id: str
+
+
+type CIContextObservation = CIContextAbsent | CIContextInvalid | ObservedCIContext
+
+_REPOSITORY_COMPONENT = re.compile(r"^[A-Za-z0-9._~-]+$")
+
+
+@dataclass(frozen=True, slots=True)
+class _ProviderSpec:
+    provider: str
+    server_variable: str
+    repository_variable: str
+    revision_variable: str
+    run_variable: str
+
+
+_PROVIDERS = {
+    "forgejo-actions": _ProviderSpec(
+        "forgejo-actions",
+        "FORGEJO_SERVER_URL",
+        "FORGEJO_REPOSITORY",
+        "FORGEJO_SHA",
+        "FORGEJO_RUN_ID",
+    ),
+    # Gitea's native gitea.* values are expression contexts; its documented
+    # process environment retains GITHUB_* for these identity fields.
+    "gitea-actions": _ProviderSpec(
+        "gitea-actions",
+        "GITHUB_SERVER_URL",
+        "GITHUB_REPOSITORY",
+        "GITHUB_SHA",
+        "GITHUB_RUN_ID",
+    ),
+    "github-actions": _ProviderSpec(
+        "github-actions",
+        "GITHUB_SERVER_URL",
+        "GITHUB_REPOSITORY",
+        "GITHUB_SHA",
+        "GITHUB_RUN_ID",
+    ),
+    "gitlab-ci": _ProviderSpec(
+        "gitlab-ci",
+        "CI_SERVER_URL",
+        "CI_PROJECT_PATH",
+        "CI_COMMIT_SHA",
+        "CI_PIPELINE_ID",
+    ),
+    "woodpecker-ci": _ProviderSpec(
+        "woodpecker-ci",
+        "CI_FORGE_URL",
+        "CI_REPO",
+        "CI_COMMIT_SHA",
+        "CI_PIPELINE_NUMBER",
+    ),
+}
+
+
+def observe_ci_context(environment: Mapping[str, str]) -> CIContextObservation:
+    """Observe and validate a supported provider's ordinary environment metadata."""
+    providers = list(_detected_providers(environment))
+    github_compatible = (
+        environment.get("GITHUB_ACTIONS") == "true"
+        and environment.get("FORGEJO_ACTIONS") != "true"
+        and environment.get("GITEA_ACTIONS") != "true"
+    )
+    if github_compatible:
+        if not _is_github_environment(environment):
+            return CIContextInvalid(
+                None,
+                "GitHub-compatible CI variables lack a provider-specific marker",
+            )
+        providers.append("github-actions")
+    if not providers:
+        return CIContextAbsent()
+    if len(providers) != 1:
+        return CIContextInvalid(None, "Multiple CI provider markers were observed")
+    provider = providers[0]
+    spec = _PROVIDERS[provider]
+    try:
+        return ObservedCIContext(
+            provider=provider,
+            server=_https_url(environment.get(spec.server_variable), "CI server"),
+            repository=_repository(
+                environment.get(spec.repository_variable), "CI repository"
+            ),
+            revision=validate_source_revision(
+                _text(environment.get(spec.revision_variable), "CI revision")
+            ),
+            run_id=_text(environment.get(spec.run_variable), "CI run identifier"),
+        )
+    except (InvalidInvocationError, ValueError) as exc:
+        return CIContextInvalid(provider, str(exc))
+
+
+def _detected_providers(environment: Mapping[str, str]) -> tuple[str, ...]:
+    providers: list[str] = []
+    forgejo = environment.get("FORGEJO_ACTIONS") == "true"
+    gitea = environment.get("GITEA_ACTIONS") == "true"
+    if forgejo:
+        providers.append("forgejo-actions")
+    if gitea:
+        providers.append("gitea-actions")
+    if environment.get("GITLAB_CI") == "true":
+        providers.append("gitlab-ci")
+    if (
+        environment.get("CI") == "woodpecker"
+        or environment.get("CI_SYSTEM_NAME") == "woodpecker"
+    ):
+        providers.append("woodpecker-ci")
+    return tuple(providers)
+
+
+def _is_github_environment(environment: Mapping[str, str]) -> bool:
+    server = environment.get("GITHUB_SERVER_URL", "").rstrip("/")
+    api = environment.get("GITHUB_API_URL", "").rstrip("/")
+    if server == "https://github.com":
+        return api == "https://api.github.com"
+    return bool(server) and api == f"{server}/api/v3"
+
+
+def _text(value: str | None, label: str) -> str:
+    if (
+        value is None
+        or not value
+        or len(value) > 1024
+        or any(character.isspace() for character in value)
+    ):
+        raise ValueError(f"{label} is missing or malformed")
+    return value
+
+
+def _repository(value: str | None, label: str) -> str:
+    result = _text(value, label)
+    components = result.split("/")
+    if (
+        len(components) < 2
+        or result.endswith(".git")
+        or any(
+            component in {"", ".", ".."}
+            or _REPOSITORY_COMPONENT.fullmatch(component) is None
+            for component in components
+        )
+    ):
+        raise ValueError(f"{label} is malformed")
+    return result
+
+
+def _https_url(value: str | None, label: str) -> str:
+    result = _text(value, label)
+    try:
+        parsed = urlsplit(result)
+        port = parsed.port
+    except ValueError as exc:
+        raise ValueError(f"{label} is malformed") from exc
+    if (
+        parsed.scheme != "https"
+        or parsed.hostname is None
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise ValueError(f"{label} must be a credential-free HTTPS URL")
+    authority = parsed.hostname.lower() + ("" if port is None else f":{port}")
+    return urlunsplit(("https", authority, parsed.path.rstrip("/"), "", ""))